How to interpret the payment responses
The payment responses have the same format for all integrations with the gateway, including the iframe checkout (COPYandPAY), SERVER-TO-SERVER, and back-office API operations.
Approved transactions
If a transaction is approved, the gateway's response.code will be 000.000.000 in the live environment. And the accompanyingdescription provides a detailed explanation of the transaction result. In the test environment, there are more approval codes. For full details, see Gateway result codes.
For approved transactions, the transaction response will have a SchemeResponseCode with a value of 00.
An approved recurring payment will also have a Merchant Advice Code or Visa Category Code with a value of 00.
Transaction approval flow
The information in the transaction resultDetails section will depend on which stage in the approval process the transaction reaches before it is declined.
The transaction approval flow goes through the entities in this order.
- Gateway
- Acquirer
- Card Scheme
For example, if a card is expired, the gateway will decline the transaction, and it will not reach the acquirer or issuer.
Here is a diagram of a transaction response flow.
Transaction response flow
The gatewayresponse.code always provides detailed information together with the description. See Gateway documentation of result codes.
Declined transactions
If a transaction is declined, the gateway's response.code will be non-zero, and the other response codes you receive will depend on which entity declined the transaction, as shown in the transaction approval flows section above.
For example, a gateway response code of 800.100.152 (with the description value of transaction declined by authorization system) means the issuer declined the transaction.
In this case, you will also receive a non-zero SchemeResponseCode, which will provide more details.
Here is a table of some of the attributes that may be in the payment response.
| Section | Attributes | Description |
|---|---|---|
| Main response section | id | A unique identifier for the transaction in the gateway |
resultDetails | code | The gateway response code. If the gateway declines the transaction, this may be the only response information. An example of an issue that causes a decline in the gateway is an expired card. The other decline response codes are for errors with 3D Secure (3DS) and the external bank. For a detailed list, see Gateway result codes for rejected transactions |
AcquirerResponse | The acquirer may decline the request before it reaches the schemes or issuer, and it will provide this code. The reason why a transaction was declined is in the Extended Description field. | |
SchemeResponseCode | This code is provided by the scheme or issuing bank when they approve or decline the request. This is a set of standard codes defined by the schemes and extended by the issuing banks. The reason why the transaction was declined is in the Extended Description field. | |
| Visa Category Codes and Merchant Advice Codes | See Declined recurring transactions below. | |
card | ALL | Details of the card used for this transaction. |
threeDSecure | ALL | Details of 3DS verification of the transaction. The ECI flag is the result code for 3D Secure authentication. See ECI flags for 3D Secure authentication |
Declined repeated transactions
When the scheme or issuing bank declines a recurring transaction (for instalments, subscriptions, and metered orders), they provide a Visa Category Code or Merchant Advice Code.
These codes define whether you can retry a recurring billing event or not.
- If a transaction is hard-declined, you cannot retry it.
- If a transaction is soft-declined, you can retry it up to 15 times in the next 30 days.
See the table below to interpret the codes.
In addition to these codes, the scheme response code can give you more details about why the transaction failed. If there is no Merchant Advice Code or Visa Category Code and the transaction is declined, it is possible that the transaction was soft-declined or failed at the payment gateway.
Table of Visa Category Codes (VCCs) for Visa
| Description | Visa Category Code (VCC) | CardCorp |
|---|---|---|
| Approved | 0 | Approved |
| Issuer will never approve | 1 | Hard-declined |
| Issuer cannot approve at this time | 2 | Soft-declined |
| Data quality issues / revalidate data | 3 | Soft-declined |
| Generic response codes | 4 | Soft-declined |
Table of Merchant Advice Codes (MACs) for Mastercard
| MAC Code | Description | CardCorp |
|---|---|---|
| 00 | Approved | Approved |
| 01 | Updated/additional information needed | Soft-declined |
| 02 | Try again later | Soft-declined |
| 03 | Do not try again | Hard-declined |
| 04 | Token requirements are not fulfilled for this token type | Soft-declined |
| 21 | Payment cancellation | Hard-declined |