Invoices
Once a customer has been created, invoices/plans will need to be attached to a customer. This will allow payments to be deducted from the customer's account. There are 2 invoice models that can be chosen for this component:
1. On- Demand Model
Ezypay will not hold any schedule for re-occurring payments. The integrator will send in a create invoice API to trigger Ezypay to attempt a payment when it is required. All schedules will be handled by the integrator.
2. Subscription Model
Ezypay will handle the schedule of when the re-occurring payments will be attempted. Ezypay will follow the created schedule based on the subscription created by the integrators. This is the preferred integration model.
Regardless of which invoice model you use to integrate with Ezypay, the way that invoices behave are the same. Below is a process flow displaying how invoice processing works.
Invoice Processing - Money Flow Diagram
It will clearly show how the money flows between you (the integrator) and Ezypay. It displays at each event what actions will take place, based on what API and webhook was used and the various paths that the money flow could go. Depending on what the scenario is, it will help you understand what parameters should be used and how they can be incorporated into your application. For example:
- The difference between what payment method the invoice was collected via (e.g bank vs credit card)
- If the Ezypay fees collected were customer or merchant paid
- The difference between the status of an invoice (successful or failed)
Managing Invoices for Subscription Model
The invoice Management Process is broken up into 2 important sections, the first is for invoices generated through the subscription, and the second is the invoice history that occurred (Failed).
As the schedule of each invoice is handled by Ezypay, it’s important to be able to display and track future invoices from a subscription:
a. Integrators need to use the future invoice API to retrieve all upcoming invoices and the date of when these invoices will be attempted.
b. The status of the invoice, including their failed payment reason needs to be visible to the merchants.
Making changes (to future invoices):
a. Integrators will need to use the “UPDATE Future Invoice API” to update any future invoices.
b. Any updates leading or after the first collection will need to be actioned using the “Edit Subscription” API.
c. Any requirements to stop the subscription is handled by using the “Cancel Subscription” API.
Correct Invoice Statuses
a. Integrators will also need to be able to track the invoice that was previously attempted using the GET invoice list API (historical).
b. The status of the invoice, including their failed payment reason needs to be visible to the merchants. The important webhook that is needed is the “invoice_past_due” – also see failed payment handling section below for more details.
IMPORTANT NOTE:
Any future invoice “date” needs to be updated within the current invoice “cycleStartDate” and the current invoice “cycleEndDate”. This is to prevent any overlapping of invoice that will be created on the “date”. Get this data from Future Invoice API.
Future invoices will always be in a virtual state until the “date” of the invoice is met. All future invoices will become physical invoices during the early morning on the set “date”. Depending on the type of payment method used, the payments will be attempted at different times.
Definition of Invoice Statuses
The invoice status is important to be displayed to the merchant, so that they can ensure the correct next action to the invoice is done.
| Invoice Status | Definition | Possible Next Actions |
|---|---|---|
| PROCESSING | An invoice in which payment collection is currently in progress where its transaction has yet to be returned as success or failed by the bank | No action can be done whilst the invoice is in this status. Merchants will need to wait until the invoice status has been updated to another status (example PAID and PAST_DUE being the common status). |
| PAID | - An invoice with successful payment collection - An invoice that has been marked as Paid due to external payment collected | Refunds or partial refunds can be actioned (provided there are enough funds in the merchant wallet) |
| PAST_DUE | An invoice that has been updated to PAST_DUE to one of these reasons: - Attempted payment collection returned as failed and no further attempts were scheduled - No attempted payment on due date because no payment method is linked - A chargeback/dispute | When an invoice is PAST_DUE, you can - Retry the payment manually via the API call. - Write-off an invoice to stop any attempt for recollecting this payment. - Record an external payment used to collect this payment. - Update the invoice to add a discount to the invoice (to reduce to the total amount to be collected). In using Ezypay's failed payment services, leaving the invoice as PAST_DUE will allow the failed payment system to auto recollect those payments via our (Auto rebill and Failed payment notification process). |
| UNPAID | - An on-demand invoice is created with a scheduled payment date in the future - A failed invoice that has been automatically set to rebill in a future date - A failed invoice that had its scheduled payment date updated to a future date for collection | - Invoices that has not been attempted (future dated invoice), merchants will not be charged fees if the invoice was: a) Written-off b) Recorded as PAID (collected externally). - Invoices that has been attempted and an auto-rebill is in scheduled. Fees will be reallocated to the merchants if: a) Written-off of the invoice b) Recorded as PAID (Only the Ezypay fees will be reallocated to the merchants). - If integrators/merchants choose to stop the auto re-bill process by updating the invoice "scheduledPaymentDate" to null. |
| PENDING | An invoice is scheduled for payment collection but: - billing could not be processed, possibly because billing has been disabled for the merchant, - or billing has yet to be processed for the day (pending billing to be run). | - Invoice can be written-off or record as externally collected with invoice is in this status. NOTE: Most of the time the Pending status appears on invoice generate by Ezypay subscription model. |
| PARTIALLY_REFUNDED | A partial amount of the total paid amount has been refunded | Separate attempts to do additional partial/full refunds is possible (up until the initial collected amount). |
| REFUNDED | The entire amount has been refunded | No actions available |
| WRITTEN_OFF | A Past Due (failed)invoice that has been written off because you no longer want to collect payment for it | Once the invoice has been written-off, there is no next action available. Fees will be reallocated to the merchant |
Updated 5 months ago