Failed Payments

There are different reasons as to why a failed payment may have occurred. These failed payment reasons are provided by the banking institution to Ezypay.

Ezypay will map these failed payments and reasons against the customer’s record accordingly.

The failed payment reasons include:

  • Payment Token Issue
  • Insufficient Funds
  • Invalid Account Details
  • Card/Bank Provider Declines Transaction (Customer to Contact bank)

It is a requirement that all integrators must have completed all the mandatory items below, as part of the integration process.

Mandatory Items
1. Integrators must be able to show clearly why the payment failed, using the information provided by either the "invoice_past_due" webhook event or using Ezypay's "GET Invoice" API. The failedPaymentReason will provide clarity as to why the payment failed.
2. Integrator must be able to handle invalidated payment method token, by replacing the faulty payment method token with a newly created payment method token, using our Replace payment method API.
3. Integrator must have the ability to allow the merchant or customer to retry the invoice based on the failed payment OPTIONS below.

Below is a simple process flow:




A failed payment can occur 1 to 3 days after the debit request has been made due to a delay on the payment processor side. (Eg: Bank accounts)

Invoices with the payment status set to "Past Due" are invoices that have failed or are unsuccessful.

When a payment has been set to "Past Due, there are 2 options available:

  1. To retry the failed payment invoice, or
  2. To write-off the failed payment invoice

There are a few ways to handle the collection of failed payments (also known as a "retry"). The table below outlines some failed payment options and if they can be handled by Ezypay or the integrator.



Steps to setup your Ezypay POSTman environment:

Guide to setting up Ezypay's POSTman sandbox environment

Manual Retry API collection:

In case of missing button, just click import on your POSTman application and select "Link":

If a retry for a failed payment invoice is not required, you will be given the option to write-off the invoice. A write-off is similar to cancelling or removing the invoice.

If a write-off is performed against an invoice, the invoice status will be set to "Written Off" and no further billing retries will be attempted for that specific invoice.



  • If the option to write-off a payment is selected then all customer paid fees will be absorbed by the merchant. These fees are taken from the merchant's settlement.

  • The option to "Write-off" a payment is only available when the invoice status is marked as "Past Due".

OPTION 3: Pay Now Link
The Pay Now link allows a merchant's customer to make an immediate online payment via the payment link.

When a payment fails, Ezypay will send a failed payment notification email to the customer. The email will advise the customer the payment had failed on which date, and the total amount outstanding. It will give the customer the option to make an immediate online payment via the payment link (PayNow).

How-To Guide: Failed Payments

  1. How to retry/rebill a payment when it has failed

  2. How to write off a payment if the failed payment was settled outside of Ezypay's system

  3. Immediate Online Payment for failed payments



By default, the failed payment will have a stackable failed payment fee charged to either the paying customer or the merchant (depending on what is agreed between Ezypay and the merchants during the merchant on-boarding process).

Every retry will incur an Ezypay transaction fee based on what is agreed during the merchant on-boarding process.