Interact Response Handling

Overview

When processing authorization requests, clients must verify the request from Qolo and respond with a structured response payload that indicates whether a transaction is approved, partially approved, or declined. These responses should include decision codes, funding details, and optional overrides, such as AVS checks and partial authorization amounts.

This section outlines the response payload structure, explains the meaning of various response codes, and describes how partial authorization works when full approval is not possible. By understanding these response mechanisms, clients can optimize the transaction approval process while ensuring compliance with Qolo's authorization and funding workflows.


Verify Transaction Request

Every transaction payload sent to a client’s system will include a hashed version of the payload in the request header under the field x-qolo-signature. Using a library or algorithm of their choice, clients should verify the hash using SHA-256. The result of this verification should match the x-qolo-signature sent in the header. This step is crucial to confirm that the request originated from Qolo.

Example:

// Create HMAC using the secret

var crypto = require('crypto');

const hmac = crypto.createHmac('sha256', '<CLIENT SECRET>');
  
const payload = '<TRANSACTION PAYLOAD IN RAW FORMAT>';
  
// Update the HMAC with the payload and get the digest in hexadecimal format
const computedHash = hmac.update(payload).digest('hex');

// the value will be the same as the x-qolo-signature
console.log(computedHash);

Response Payload Fields

When making an authorization decision, clients must return a structured response to Qolo. The response payload consists of the following required and optional fields:

Field NameDescriptionRequired
response_codeThe final decision on the transaction (APPROVE or DECLINE).✅ Yes
reason_codeThe reason for declining the transaction (only required for declines).✅ Yes (if declined)
pf_account_guidThe program funding account ID (only for clients with multiple accounts).Optional
partial_auth_amountThe approved transaction amount (if the merchant supports partial authorization).Optional
avs_resultAVS check result override (if applicable). Values
U: Address information is not available for the customer's credit card
X: exact street match and zip match
Y: Street address and first 5 digits of the ZIP code match perfectly
A: The street address matches, but the 5-digit ZIP code does not
W: 9 - digit ZIP code matches, but street address does not
Z: First 5 digits of ZIP code matches, but street address does not
N: Neither street address nor 5 - digit ZIP code matches address and ZIP code on file for card
S: U.S.card issuing bank does not support AVS
G: address information not verified for international transaction
Optional
{
    "response_code": "APPROVE",
    "reason_code": "",
    "pf_account_guid": "",
    "partial_auth_amount": "",
    "avs_result": "", //U, X, Y, A, W, Z, N, S, G
}

Possible Response Codes and Their Meanings

Clients may approve or decline transactions using the following standard response codes:

Reason CodeResponse CodeDescription
APPROVEAPPROVALTransaction successfully completed and approved.
CASH_REQ_EXCEEDDECLINECash request exceeds issuer or approved limit
CLOSED_PICKDECLINECard closed, deny & pickup
AUTH_DECLINEDECLINEAuthorization Declined
DO_NOT_HONOURDECLINEDo not honor, deny.
FRAUDULENT_PICKDECLINEFraudulent use, deny & pickup.
INSUFF_FUNDSDECLINEInsufficient funds, deny.
INVALID_MERCHANTDECLINEInvalid merchant.
NO_ACTIONDECLINENo action taken.
NO_CASH_SERVICEDECLINECash service is not available for this transaction.
PART_AUTHAPPROVALPartial Auth.
RESTRICTEDDECLINERestricted card (invalid in a region or country), deny.
SEC_ERRORDECLINESecurity error, authentication failed, deny.
SUSPECT_FRAUDDECLINETransaction flagged as suspected fraud.
TXN_NOT_PERMITDECLINETransaction not permitted for this cardholder.
VELOCITY_EXCEEDDECLINEFrequency limits exceeded, deny.

Partial Authorization Handling

Partial authorization allows transactions to be approved for a lower amount than originally requested when the full transaction amount cannot be funded. This feature is typically only supported for certain merchants and must be enabled in the client’s configuration.

Partial Authorization Process

  1. A merchant sends a request for a specific transaction amount.
  2. The client determines that full approval is not possible (e.g., due to funding limits or account restrictions).

Instead of declining the transaction outright, the client responds with:

{
   "response_code": "APPROVE",
  "partial_auth_amount": "50.00"
}
  1. This tells Qolo that the transaction is approved for $50.00 instead of the full requested amount.
  2. The merchant may accept the partial approval and process the transaction at the reduced amount.

Considerations for Partial Authorization

  • Not all merchants support partial approvals.
  • If a merchant does not accept partial authorization, they may cancel the transaction instead.
  • If AVS overrides are used, they must still comply with Qolo's security requirements.
  • Velocity checks apply, meaning excessive partial approvals within a short timeframe could trigger fraud alerts.

Summary of Authorization Decisioning

ScenarioResponse TypeOutcome
Client approves full amountAPPROVETransaction is fully approved.
Client declines the transactionDECLINETransaction is rejected.
Client does not respond in 3 secondsDECLINE (by default)Transaction is automatically declined.

Key Takeaways

  • Clients must respond to authorization requests within 3 seconds to avoid automatic declines.
  • Response payloads must include response_code and reason_code (if declined).
  • Partial authorizations allow transactions to proceed at a lower amount when full funding is unavailable.
  • Qolo handles funding in Interact Funding and Gateway Funding, while clients must manage their own balances in Interact Gateway.

Related Topics