Immediate Online Payment (PAY NOW) Recovery Option
This article will outline what is the immediate Pay Now option and how this can be configured
What is the Pay Now Failed Payment Recovery Option and How it can be Configured
The Pay Now failed payment feature gives the customers the option to make an immediate payment online for their failed payment. Ezypay will send a failed payment notification via email to the customer with a Pay Now link associated with their failed payment. It will also allow the customer to create a payment method token.
This feature is suitable for both the on-demand and the subscription model. Both models can enable the Ezypay PAY NOW feature. If you would like this feature to be enabled for your merchants, please inform Ezypay during the merchant on-boarding process. This feature can be enabled on the merchant level and is not based on a selected invoice/customer.
With the Pay Now failed payment option, customers are also given the option to update their payment method token at the same time. Integrators will need to determine if they would like the customers to have the option to replace their existing payment method token as well as pay for their failed invoice or only allow the customer to pay for their failed invoice.
With this option, customers can only pay for the full amount of their failed payment. This will be the debit amount plus any fees that the customer is required to pay. There is no option for the customer to make a partial payment.
Options to Successfully Configure the Pay Now 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
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 “channel” in the return payload.
d) There will be a “payNowUrl” provided by the webhook event if the failed payment/PAY NOW email was enabled on the merchant setup.
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 action their invoice recovery process.
With the information provided from the webhook response for the “invoice_past_due” event, the “important parameter” (namely “channel” and “payNowUrl”) will allow the integrators to identify if there will be an action required by the merchant/customer.
2. Pooling Ezypay’s [GET] invoice API
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 what the “channel” is for the current invoice.
c) Identify there is a “payNowUrl” provided for an invoice that failed.
It would be best practice 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.
How the integrator can differentiate a normal invoice VS a PAY NOW retried invoice
The “channel” parameter plays an important part to allow the integrator or merchant to know if this invoice was attempted as a normal payment or was the payment retried through a PAY NOW option.
In any case, if the invoice was generated by calling Ezypay “Create invoice” API, the result of this parameter will be “api”.
If this invoice was retried via the PAY NOW option, the “channel” will be updated to “online_payment_recovery” instead of the “api”. Most of the time this invoice will be returned with a “PAID” status.
The “payNowUrl” is also a very good indicator that a failed payment notification was sent to the customer's email address. This parameter will consist of the link which was added to the failed payment email which was sent to the customer.
With the Pay Now setting, Ezypay allows the customer's primary payment method token to be replaced with the one they are using at Pay Now. But this setting can be disabled during the merchant on-boarding process. The option to replace the payment method will be removed and only allow the customer to reattempt this failed payment with a new payment method as a once off.
Limit to the Pay Now retry:
The Pay Now can only work if the payment is still in “PAST_DUE”. If the invoice was written off or PAID off via a different method, the Pay Now link will not charge the customer again. If a customer attempts to make a payment with the Pay Now link but the failed invoice has already been paid for, there will be a message to inform the customer that the Pay Now link is no longer valid because this payment has already been collected successfully.
There is currently no expiry on the Pay Now link, as long as the invoice is still marked as “PAST_DUE” this PAY NOW link will still work.
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.
|“channel”||The result to this parameter is very important to inform integrators if this payment was collected via the create API call or was this invoice re-attempted using the PAY NOW option|
a) “api” here means this invoice was attempted via the normal invoice creation process.
b) “online_payment_recovery” here means the payment re-attempted using the PAY NOW option.
If the invoice status is still “PAST_DUE” and the channel is “online_payment_recovery”, this mean that the invoice was re-attempted using the PAY NOW scenario, and it still failed.
|“payNowUrl”||The URL that the customer will receive, along with the failed payment email will be the similar URL displayed in this parameter.|
This can act as an indicator that a failed payment notification, as well as the PAY NOW link was emailed to the customer.
|“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”.
|“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 indicated 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 older payment method token.
Updated over 2 years ago