Handling Errors

When processing payments, several errors can occur that are outside of your or Dibsy's control. For example, the customer has insufficient funds in their card or the issuing bank could decline the transaction.

In order to provide a great user experience, handling errors is extremely important. If transaction fails, you must handle it gracefully by informing the customer of the error so they can correct the problem and complete the checkout. Please find below a list of all possible failure reasons and accompanying failure messages that you can display to your customer in case of failure.

Error Messages

FAILURE REASON	FAILURE MESSAGE
unknown_reason	The card has been declined for an unknown reason. Please try a different card or another payment method.
naps_card_not_permitted	The NAPS card is not permitted for this type of transaction. Please use the “Debit card” option.
invalid_cvv	The CVV provided does not match the information on file with the cardholder's bank. Please try again or contact your bank.
ip_not_permitted	The transaction was made while connected to a VPN, using a proxy or from an unusual IP address. Please turn off proxies and try again.
refused_by_issuer	The customer's card issuing bank has declined the transaction. Please use a different card or another payment method.
insufficient_funds	There is an insufficient balance in your bank account. Please use a different card or another payment method.
card_expired	The card is expired. Please use a different card or another payment method.
invalid_card_number	The customer's card issuing bank is unable to validate the card number. Please try a different card or another payment method.
possible_fraud	The card issuer indicated a security issue with this card and is suspected of fraud or stolen. If you believe this to be an error, please contact your bank.
card_declined	The card has exceeded the withdrawal limit. Please use a different card or another payment method.
authentication_failed	The card authentication has failed. Please check your card details and try again.

How can I find out what error occurred?

If creating the payment has failed, the GET Payment API response will contain a failureReason code and failureMessage in the details object.

Example Payments API response for failed payment

Note that some fields have been omitted for simplicity.

HTTP/1.1 201 OK
Content-Type: application/hal+json

{
    "id": "pt_5OffTEpLJQDimoD0SU",
    "resource": "payment",
    "mode": "live",
    "amount": {
        "value": "1.00",
        "currency": "QAR"
    },
    "details": {
        "cardCountryCode": "QA",
        "cardExpiry": "10/25",
        "cardHolder": "Tanish Panjwani",
        "cardLabel": "Mastercard",
        "cardNumber": "5500 00XX XXXX 3102",
        "failureMessage": "The card authentication has failed. Please check your card details and try again.",
        "failureReason": "authentication_failed"
    },
    "createdAt": "2022-04-22T12:52:09.196",
    "failedAt": "2022-04-22T12:52:22.814",
    "_links": {
        "self": {
            "href": "https://api.dibsy.one/v2/payments/pt_5OffTEpLJQDimoD0SU",
            "type": "application/hal+json"
        },
        "dashboard": {
            "href": "https://console.dibsy.one/payments/pt_5OffTEpLJQDimoD0SU",
            "type": "text/html"
        },
        "documentation": {
            "href": "https://api.dibsy.dev/#operation/Get%20Payment",
            "type": "text/html"
        }
    }
}