Response handling

When a resource like a payment or a refund is created, we will generate and return a unique identifier ( paymentId , refundId ) along with its status . You should store it as you will need them to perform follow-up operations. Each operation response (creation or follow-up operation) will contain following common set of properties to indicate the results of the operation.

• operationId : An id provided by you in the request.

• responseCode : A numeric code indicating the result of the operation.

• responseCodeDescription : A textual description of the response code.

• responseCodeCategory : A high-level indication of the result of the operation.

• responder : Showcasing the party that originated the response. All these properties are discussed in detail further down in this page.

You will also notice following object/properties in the response depending on the operation and its status.

• cardPaymentData holding the card brand name, AVS and CSC verification results.

• references object with properties like retrievalReferenceNumber , schemeTransactionId and paymentAccountReference will be returned if we happen to receive them from the scheme/issuer.

• retryAfter property indicating the duration to wait after the authorization rejection before reattempting. This will be returned only when the authorization can be retried later.

• statusTimestamp property indicating the date of the last status change. Mainly useful when you retrieve a resource some time after its creation.

• totalAuthorizedAmount object indicating the amount that is authorized. On certain condition, Issuers can approve an authorization for a partial amount. You must always look at this object to know the actual authorized amount and decide on the next course of action on your platform.

• either initialAuthorizationCode or authorizationCode depending on the operation.

Status

Our Acquiring platform, depending on the API call returns the status of a resource (payment or refund). This can be either the newly created resource status or the status of already existing resource.

Property "status"

The values listed in the table below apply to the following properties of respective API endpoints.

• status : create payment / create refund / retrieve payment / retrieve refund

• payment.status : capture payment / authorization reversal / increment authorization

• refund.status : refund payment / capture refund / refund authorization reversal

Response Code Category

When processing a transaction, our Acquiring platform returns various response code categories that indicate the outcome of each operation/request. These response codes are vital for determining the success or failure of a transaction. Possible values are

• APPROVED - The requested operation has been carried out successfully and the transaction has been approved.

• PARTIALLY_APPROVED - The requested operation has been carried out successfully but the outcome needs more attention. This is returned as a result of authorization being approved for partial amount. You could either reverse the transaction or choose to proceed with the partial authorized amount.

• DECLINED - The requested operation has been attempted but couldn't be completed successfully or simply been rejected by any of the parties involved. Refer to responder to know the origin of the response. You could retry later depending on the availability of retryAfter property and its value.

Note that the responseCodeCategory is not returned for retrieve payment / retrieve refund or DCC rate .

Responder

Our Acquiring platform returns a property responder for most of the APIs indicating the origin the response. Possible values are

• ISSUER

• SCHEME

• WORLDLINE

• PARTNER - For future use, applicable only if a 3rd party processor is involved.

Response code

When processing card transactions, our Acquiring platform returns various response codes that provide crucial insights into the outcome of each transaction. These response codes are vital for determining the success or failure of a transaction.

The response codes are typically numeric values accompanied by a property responseCodeDescription . These response codes can be categorized as:

1. Approval Codes - Indicate successful transactions where the card issuer has approved the transaction amount.

2. Decline Codes - Indicate that the transaction was not approved by the card issuer. Decline codes may specify a variety of reasons, such as insufficient funds, card expired, or suspected fraudulent activity.

3. Error Codes - Highlight technical or processing issues that prevented the transaction from being completed. This may include errors such as invalid card number format or communication issues with the card issuer.

4. Referral Codes - Suggest that further verification is required before the transaction can be approved. This may prompt the merchant to contact the card issuer or direct the cardholder to their bank.

5. Informational Codes - Provide additional information about the transaction's processing status, which may not necessarily indicate approval or decline but offer context for further actions or reviews.

Below is a comprehensive table listing the response codes returned by our Acquiring platform. Familiarity with these response codes ensures that you can effectively manage and respond to transaction outcomes, enhancing the overall payment processing experience for your customers.

The response codes are organized in ranges in the following way:

Mapping between the 1987 version of ISO 8583 alphanumeric codes and the numeric responseCode as returned by the API is given below.