Auto-Rebill Recovery Option
This article will outline what the Auto-rebill option is and how this can be configured
What is the Rebill Payment Recovery Option and How it can be Configured
An auto-rebill will be set automatically when a customer has a failed payment. When a rebill will take place will be dependent on what has been configured at the merchant level. This is what we call rebill after X days. For example a merchant can set to rebill their customers 3 days from the failed payment notification.
The auto-rebill option can be use for both on-demand and our subscription integration model and can be configured through Ezypay's platform for each of the merchant. Rebill will only be triggered if the invoice is “PAST_DUE” and the payment method token is valid (Invalid payment method tokens will not trigger a rebill).
Options to Successfully Configure the Auto-Rebill 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.
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 are able to action their invoice recovery process as soon as possible.
With the information provided from the webhook response for the “invoice_past_due” event, the “important parameter” mention below will allow the integrators to identify if there will be an action required by the merchant/customer.
Replace the payment method accordingly using the “breakdown if the payment method has been invalidated”.
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) 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.
Replace the payment method accordingly using the “breakdown if the payment method has been invalidated”.
What is Required if the Payment Method has been Invalidated
If the paymentMethodInvalid is "true", the integrator will need to update the merchant/customer that they are required to "replace" the payment method before the scheduledPaymentDate that has been scheduled.
If a new payment method token is "replaced" before the scheduledPaymentdate, the auto rebill will be attempted on the mentioned date. If no new payment method token has been "replaced" then no attempt on the invoice will be made.
Invoice status will remain as "PAST_DUE" until the date of the scheduledPaymentDate. 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.
If integrators are setting up more than 1 auto-rebill attempt scheduled, its best to call Ezypay's [GET] transaction API (filtered by the documentId, which is the Invoice Id).
This allows the integrator to get a counter on how many attempts has been attempted by this invoice.
The first counter will always be the initial attempt, So if the Integrators would like to know how many rebill attempts was actually attempted, they should use the total counter - 1 (the initial attempt).
What is Required for the Invoice Details
The important parameter 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 informs integrators to know 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 be a process required to inform the merchant and their customer to create a new payment method token and “replace” the payment method token before any new invoices or re-billed is actioned. If the payment method token is still valid, there will not be a required process to get the merchant or their customer to re-create and “replace” a new payment method token. The existing payment method token can still be used. |
| “failedPaymentReason” | Integrators will need display the result of the “failed payment reason” in their application. This allows the merchants and their customers a clear reason as to why their payment had failed. The information provided here, acts as an indicator 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 reflexing the total amount which now needs to be collected. The “amount” includes all Ezypay fees (if any) as well as the initial re-occurring amount. |
| “fail payment fees” | This parameter returns failed payment fees details which will provide details on how much the “failed payment fees” was charged. Do note that if the customer that has more than 1 failed payment fees charged onto that invoice, these items will appear as a separate object with the same “type”. |
| “scheduledPaymentDate” | The “scheduledPaymentDate” information is very important. The date provided in this parameter will be the date that the rebill will occur. If the “payment method token” is invalid, the integrators will need to notify their merchants when the date of the rebill will be, so the merchants can contact their customers to obtain a new payment method before the rebill date. If the date of the rebill is due and the “payment method token” associated to this failed invoice is still “invalid”, Ezypay will not attempt to rebill this invoice. |
| “status” | The “status” information provides the integrator the current status of this invoice. Most of the time this will be in the “PAST_DUE” status. Invoice status will remain as “PAST_DUE” until the actual rebill date. Its important to note that if invoice status is in “PAST_DUE”, integrators can still “write-off” or “record the payment as externally collected”. Once the invoice status changes to “PROCESSING”, integrators will need to wait until the “status” is changed to either “PAID” or “PAST_DUE” again. |
| “customerId” | The customer ID is used to identify who this invoice belongs to. 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 the payment method token is “replaced”, the new payment method token will replace the older payment method token. Any new rebills will be debited from the new payment method token. |
Updated over 3 years ago