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.