Merchant advice

Overview

The merchant advice feature provides detailed error descriptions to help merchants determine appropriate next steps when transactions are declined. This information is delivered through a new field called merchant_advice in the Charge response.

Implementation details

Response format

The merchant advice is included in the JSON response as follows:

{
    "object": "charge",
    "failure_code": "payment_rejected",
    "failure_message": "Issuer Declined: By Issuing Bank",
    "merchant_advice": "Request was declined by Issuer. In case of JCB card, it might relate to incorrect personal details. Do not retry transaction with same card. Contact Issuer for more information."
}

Error message standardization

Error messages are unified across all backends, ensuring consistent messaging regardless of the card scheme or configuration when the underlying issue is identical.

Optional numeric code

On request, an additional field called merchant_advice_code can be enabled to provide the error message in integer format. The reference documentation provides a comprehensive list of these codes.

Example response with merchant advice code:

{
    "object": "charge",
    "failure_code": "payment_rejected",
    "failure_message": "Issuer Declined: By Issuing Bank",
    "merchant_advice": "Request was declined by Issuer. In case of JCB card, it might relate to incorrect personal details. Do not retry transaction with same card. Contact Issuer for more information.",
    "merchant_advice_code": "9101"
}

Testing guide

Test card information

You can test this feature in Test Mode using the following dedicated test card:

Generating specific responses

To generate specific merchant advice responses, set the transaction amount to match the desired merchant_advice_code (refer to the References section for the complete list of codes).

Example test case

To generate a specific declined response:

1. Create a charge with:

   • PAN: 4111 1111 1117 0018
   • Amount: 9132

2. Expected response will include:

merchant_advice: "Card has been temporarily blocked. Retry with a different card, or use another payment method, or Contact the Issuer for more information."

References

For a complete list of Merchant Advice values, please refer to the merchant_advice_code.xlsx file.