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 Name | Description | Required |
---|---|---|
response_code | The final decision on the transaction (APPROVE or DECLINE). | ✅ Yes |
reason_code | The reason for declining the transaction (only required for declines). | ✅ Yes (if declined) |
pf_account_guid | The program funding account ID (only for clients with multiple accounts). | Optional |
partial_auth_amount | The approved transaction amount (if the merchant supports partial authorization). | Optional |
avs_result | AVS 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 Code | Response Code | Description |
---|---|---|
APPROVE | APPROVAL | Transaction successfully completed and approved. |
CASH_REQ_EXCEED | DECLINE | Cash request exceeds issuer or approved limit |
CLOSED_PICK | DECLINE | Card closed, deny & pickup |
AUTH_DECLINE | DECLINE | Authorization Declined |
DO_NOT_HONOUR | DECLINE | Do not honor, deny. |
FRAUDULENT_PICK | DECLINE | Fraudulent use, deny & pickup. |
INSUFF_FUNDS | DECLINE | Insufficient funds, deny. |
INVALID_MERCHANT | DECLINE | Invalid merchant. |
NO_ACTION | DECLINE | No action taken. |
NO_CASH_SERVICE | DECLINE | Cash service is not available for this transaction. |
PART_AUTH | APPROVAL | Partial Auth. |
RESTRICTED | DECLINE | Restricted card (invalid in a region or country), deny. |
SEC_ERROR | DECLINE | Security error, authentication failed, deny. |
SUSPECT_FRAUD | DECLINE | Transaction flagged as suspected fraud. |
TXN_NOT_PERMIT | DECLINE | Transaction not permitted for this cardholder. |
VELOCITY_EXCEED | DECLINE | Frequency 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
- A merchant sends a request for a specific transaction amount.
- 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"
}
- This tells Qolo that the transaction is approved for $50.00 instead of the full requested amount.
- 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
Scenario | Response Type | Outcome |
---|---|---|
Client approves full amount | APPROVE | Transaction is fully approved. |
Client declines the transaction | DECLINE | Transaction is rejected. |
Client does not respond in 3 seconds | DECLINE (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
Updated 13 days ago