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.

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.