This document outlines in detail how a merchant application could integrate with Zepto in a way that will allow them to manage multiple merchants and facilitate payment requests (Direct Debits) from a customer to a merchant without any money flowing through the main applications bank account.

Throughout this guide, the following terminology will be used

You will essentially have two types of Contacts that you will be creating and debiting/crediting. Firstly will be the managed merchants. Managed merchants are the companies that will be utilising your integration to create direct debits from their customers. The other type of contact will be the customer which is the user of your merchants and is the party being debited.

When a managed merchant wishes to debit their customer, you will be creating a Payment Request from the customer that will settle into an account float. Once this Payment Request clears, you will be creating a Payment from your account float to the managed merchant who is due to receive the funds for the transaction. The total time from creation to the managed merchant receiving the funds can be up to three business days.

This integration could be broken down into two parts that each involve a couple of steps:

1. Managed merchant and Customer On-Boarding

and

2. Direct Debit Creation and tracking

The managed merchants that will be initiating the direct debits and the customers being debited will need to be added as Contacts within your Zepto account and, as there may be the need to Direct Debit both of them depending on the scenario, there will also need to be an agreement in place which is basically the authority to direct debit their account.

An Agreement is not needed in order to pay this contact, however, since there are scenarios in which either contact type may need to be debited, we recommend that you follow this guide and onboard them using the unassigned agreements endpoint so that all edge cases are covered.

When a managed merchant wishes to sign up to your service or a previously added merchant wishes to add a customer to be debited, you will first of all need to generate an Agreement link to direct them to. This can be done through the Unassigned Agreement endpoint and you can customise the resulting page and pre-fill any known data by adding query strings to the URL prior to redirecting this merchant. The available customisation options are documented here.

Example white-label, pre-filled agreement page

Both parties can also have the option of entering their BSB and account number rather than providing their online banking credentials. This option is enabled by appending the query string, allow_manual=1 to the end of the unassigned agreement link that was retrieved earlier. Please note that this option needs to be enabled in your Zepto account by the Zepto team, so please reach out to have this enabled.

Example white-label, pre-filled agreement page using allow_manual=1

When this link is followed and banking credentials or BSB and account numbers are entered, two things will happen. A Contact will be created and an Agreement will be put in place between your account and this contact. This agreement is basically the authority to Direct Debit this contact and will need to be in place.

You can use multiple methods to be notified when this happens, each of these is outlined in this article. We recommend using our webhook system for this and each time an Agreement is created, you will receive a webhook that will contain all details and ID's that you will need to persist within your system.

Example Received Webhook

Note: In particular you will need to store the contact_id as this will be used in future API calls to request payment from and send payment to this contact.

Once you have this ID it's as simple as one GET request to the contacts endpoint to retrieve any other details you wish to store such as contact name, email or bsb and account number should you need to.

Now that you have a managed merchant and their customer's setup as contacts within Zepto and have persisted their Contact IDs, you are ready to create a Payment Request (Direct Debit) from the customer.

The payment request can be created by using our request payment endpoint and is as simple as telling us which contact id to debit, how much we should debit, where we should settle the funds, and when we should begin processing this transaction.

Example Payment Request Payload

The authoriser_contact_id in this scenario will be the contact id related to the customer that is being debited. This id should have been persisted as explained above in the customer onboarding section.

The your_bank_account_id will need to be the id related to your float account. We will settle any debited funds into this account. If you need any information about float accounts and how to get this id, refer to our collection of articles that cover this.

Example Response

Our response to the above request includes all the details necessary to track this payment request from creation to a cleared or returned final status. We highly recommend you make use of our webhooks, explained in this article, to keep track of the progress of this transaction.

In a payment request from contact to your account float scenario, you will mainly be utilizing two webhooks to track the progress. These are:

The standard event cycle of a successful debit will look like the following

In the event of a failed payment request, this event flow will look different and may follow a path similar to the following.

or

Each of these webhook payloads will include all information needed to track a payment request from start to finish. For example, the following is an example creditor_debit.scheduled event and the parent_ref field will be shown in all subsequent webhooks for this payment request. This field alone can be used to track a transaction from start to finish.

Now that the payment request from the customer has cleared and you have the managed merchants contact id, it's time to pay the merchant for the amount of the debit. This is achieved by making one POST request.

The payment can be created by using our make a payment endpoint and is as simple as telling us which contact id to pay, how much we should credit, which account to use to fund the payment and when we should begin processing this transaction.

Example Payment Payload

The recipient_contact_id in this scenario will be the contact id related to the merchant that is receiving the funds. This id should have been persisted during the onboarding process earlier.

The your_bank_account_id will need to be the id related to your float account. We will draw the funds for this refund from this account. If you need any information about float accounts and how to get this id, refer to our collection of articles that cover this.

Example Response

Our response to the above request includes all the details necessary to track this from payment creation to a cleared or returned final status. We highly recommend you make use of our webhooks, explained in this article, to keep track of the progress of this transaction.

Payment to your managed merchant from your account float scenario, you will mainly be utilising two webhooks to track the progress. These are:

The standard event cycle of a successful payment will look like the following

In the event of a failed payment, this event flow will look different and may follow a path similar to the following.

Each of these webhook payloads will include all information needed to track payment from start to finish. For example, the following is an example debit.scheduled event and the parent_ref field will be shown in all subsequent webhooks for this payment request. This field alone can be used to track a transaction from start to finish.

Feel free to reach out if you have further questions by emailing us directly at support@zepto.com.au or clicking on the blue bubble icon from the corner of the screen.