Failed Payment Handling Information

Best practice to help Ezypay's Integrators to handle failed payment the most efficient way possible.

What should I do when I retrieve the new information from the GET invoice API response?

"paymentMethodToken": "e20a2d65-69a1-45b3-99e6-a0539be3d433", 
"failedPaymentReason": {
            "code": "invalid_payment_method",
        "description": "Payment method details are invalid. Please use a different payment method"
    },
    "paymentProviderResponse": {
        "code": "Refused",
        "description": "14: Invalid card number"
    },
    "paymentMethodInvalid": true,
    "manualRetryPossible": false
  • If the GET invoice API returns the item paymentMethodInvalid is true and the manualRetryPossible is false, this will indicate to the integrator or merchant that they should not retry on this invoice using the existing paymentMethodToken.

  • The failedPaymentReason code will be mapped by Ezypay to represent the standard code to identify the reason why the payment failed.

The JSON response below show the response the integrator will be getting from the Create Invoice API when an invalid payment method token is used to create a new invoice.

{
    "type": "invalid_request_error",
    "code": "payment_method_invalid_with_reason",
    "message": "Payment method 61b82595-2fc0-43e1-bf0e-1111111112 is invalid due to 'invalid_payment_method', description: 'Payment method details are invalid. Please use a different payment method.'"
}

If a retry payment is triggered using the invalid payment method token, integrators will get the response below:

{
    "type": "invalid_request_error",
    "code": "manual_retry_not_allowed_for_invoice",
    "message": "This invoice cannot be retried manually."
}

If the payment method token is invalid:

Payment method token is Invalid:

Integrators or merchant needs to create a new payment method token and update the payment method token for the failed payment invoice.

Integrators or merchants needs to create a new payment method token and replace the existing payment method token with newly created payment method token.

If payment method token is valid:

Payment method token is valid

Integrators or merchants do not need to replace or update the payment method token before a retry is attempted.


Did this page help you?