Manual Retry Recovery Option
This article will outline what the manual retry failed payment option is and how this can be configured
What is the Manual Failed Payment Recovery Option and How it can be Configured
A manual rebill is controlled by the integrator and advised by the merchant when the collection of a failed invoice is required, this would be on a case by case basis. So when a customer has a failed invoice, it requires an integrator to send through another request to Ezypay on when they wish for this failed invoice to take place. All future dated invoices will still take place, even though a failed invoice has not been collected.
Once an invoice has been created it will have their own lifecycle. This means that regardless of what Ezypay business model (on-demand or subscription) is used, the manual retry can be take place by calling Ezypay’s “retry invoice” API.
Special configuration is not required from Ezypay to enable this feature. As long as the integrators has the correct merchant ID and the correct Invoice ID, then this process will be available though the “retry invoice” API. It is still important to take note of the payment method tokens which have been invalidated (Ezypay will respond by informing the integrator that a retry cannot take place (due to an invalid payment method token) when the “retry invoice” API was requested.
Options to Successfully Configure the Manual Retry Feature
There are 2 options to successfully configure this feature:
- Webhook Option
- Pooling Ezypay’s [GET] invoice API
Detailed steps on how to achieve these will be listed below
1. Webhook Option - This is the preferred option
Pre-requisite:
a) Subscribe to Ezypay’s “invoice_past_due” webhook event.
b) Have a HTTP webhook listener function ready to filter the needed information.
c) Very important to identify if the payment method token is valid? (“paymentMethodInvalid”)
d) Very important to identify if this invoice can be retried? (“manualRetryPossible”)
Description:
The webhook option allows integrators to receive the quickest update for an invoice status. This allows the integrator to update their merchants so that they will be able to recover the failed invoice as soon as possible.
With the information provided from the webhook response for the “invoice_past_due” event, the “important parameter” (“paymentMethodInvalid” and “manualRetryPossible”) will allow the integrators to identify if there will be an action required by the merchant/customer.
Replacing the payment method is required. Please see section "Breakdown if the payment method has been invalidated" that has been listed below.
2. Pooling Ezypay’s [GET] invoice API
Pre-requisite:
a) Have a backend job or a CRON job running with an interval time collecting the latest status for invoices created which are still in the “PAST_DUE” status.
b) Identify if the invoice can be retried “manualRetryPossible” before a retry is triggered.
c) Identify if the payment method token used is still valid or not (“paymentMethodInvalid”)?
d) Trigger a function which will automatically update the needed components in the integrator’s application (Update invoice status and add new information as to why the payment failed).
Description:
Normally it would be best to have a job running every 3 hours starting from 7 AM daily to run an API call to retrieve the latest updated invoice status.
Replacing the payment method is required. Please see section "Breakdown if the payment method has been invalidated" that has been listed below.
Breakdown if the payment method has been invalidated
If the paymentMethodInvalid is "true", the integrator will need to update the merchant/customer that they will need to "replace" the payment method before the scheduledPaymentDate reaches.
If a new payment method token is "replaced" before the scheduledPaymentdate, the auto rebill will be attempted on the mentioned date.
Invoice status will remain as "PAST_DUE" until the date of the scheduledPaymentDate. The invoice will be updated to "PROCESSING" before either changing to "PAID" or "PAST_DUE" depending on the outcome of the attempt.
NOTE:
If the payment method token has been invalidated, the auto-rebill will not be processed (as Ezypay does not want to charge the customer another failed payment fee if the payment account is already invalid).
As each failed payment triggers another failed payment fee, and this will cause the failed payment fees will continue to accumulate.
There is no limit to the amount of manual retries that can be triggered through to Ezypay. With that in mind, it is a good practice for integrators to set a maximum number of attempts a merchant can retry on a certain invoice.
Please note that Ezypay will charge a fee for every attempt on a retry of an invoice. Most of the time this will be the transaction fees associated with the invoice. This fee will be charged to the customer or the merchant. If any special agreement is required, the merchant or integrator can contact our Ezypay’s sales team.
What is Required for the Invoice Details
The important parameters below will be provided by either calling our [GET] invoice API or in our “invoice_past_due” webhook event.
| Important Parameter | Description/Importance |
|---|---|
| “paymentMethodInvalid” | The result to this parameter (true or false) is very important as it notifies integrators that the payment method token used by this invoice is now invalid. a) “True” here means the payment method token is invalid b) “False” here means the payment method token is valid If the payment method token is invalid, there will need to be a process set up to inform the merchant and their customer that a new payment method token is required and the new payment method token needs to be updated before any manual retry can be triggered. If the payment method token is still valid, there will the manual retry can triggered immediately. |
| “manualRetryPossible” | Integrators will need to identify if this invoice can be reattempted still. a) “True” here means invoice can be reattempted. b) “False” here means invoice cannot be reattempted until some action has been completed. This usually relates to the “paymentMethodInvalid” result. So once a new payment method token is updated, the integrators will see the “manualRetryPossible” changed from “false” to “true”. |
| “failedPaymentReason” | Integrators will need display the result of the “failed payment reason” in their application. This provides the merchants and their customers a clear reason as to why their payment had failed. The information provided here, adds more indication as to why the “payment method token” has been invalidated. |
| “amount” | Integrators needs to be aware that the amount displayed in the invoice details payload is reflecting the total amount which now needs to be collected. The “amount” includes all Ezypay fees (if any) as well as the initial reoccurring amount. |
| “fail payment fees” | This parameter returns failed payment fees details which will provide details on how much “failed payment fees” was charged. Do note that if the customer that has more than 1 failed payment fee charged onto that invoice, these items will appear as a separate object with the same “type”. |
| “status” | The “status” information provides the integrator the status of this invoice. Most of the time this will be in the “PAST_DUE” status. It is important to note that if invoice status is in “PAST_DUE”, integrators can still “write-off” or “record the payment as externally collected”. The invoice status will remain as “PAST_DUE” until a new retry attempt is triggered. With that trigger, it will change from “PAST_DUE” to “PROCESSING” again. |
| “customerId” | The customer ID is used to identify who this invoice belongs too. The customer ID provided in the response payload is the Ezypay unique customer ID. |
| “paymentMethodToken” | The payment method token recorded in this response payload indicates which payment method token was used by Ezypay to collect the payment. Once a “replaced” is action, the new payment method token will replace the old payment method token. |
Updated over 3 years ago