Note: This article is relevant to merchants integrating with Zepto in Australia.
β
Webhooks are used to notify your application of changes to the status of Agreements, Payment Requests, Credits, Debits, etc as they are processed through the system.
By subscribing to our webhook events you can monitor the status of each transaction, and then trigger the appropriate next steps. While making Payments and Payment Requests, webhooks allow you to check the status of the transactions.
This article gives an overview of the webhook events you would expect to receive for the following scenarios.
Making a Payment
Via NPP
Unsuccessful via NPP (Successfully Processed via DE after channel switching)
Unsuccessful (No Channel Switch to DE) (Uncommon Configuration)
Via Direct Entry(Direct Credit)
Making a Payment Request (Direct Debit)
Receiving Funds to a PayID
Voided Transactions
Successful NPP and Direct Credit Payment
When making a payment from your bank account, since you are debiting your bank account, the debit.xx will be related to your account. The funds are being received by your end customer thus the debtor_credit.xx will relate to your end customer's side. The final webhooks events you need to listen to in this case are:
payment.added
debit.cleared
debtor_credit.cleared
- (Funds were credited into the end customer's account)
For a successful NPP transaction, the final event that the system will fire is debtor_credit.cleared
. Please note, that the above webhooks will be fired under the category payout
Note: For DC transactions, the cleared webhook does not guarantee that the funds have been settled into the end customer's account. The end customer's bank can take a few hours to settle the funds in the associated bank account.
It has been previously noticed, that for a Direct Credit transaction, the banks can get back to us after a day or two, informing us that the credit to the end customer's account has failed due to various reasons(eg: bank account closed). In this case, our system will trigger another webhook event debtor_credit.returned
under the category payout
and a bunch of other webhook events with the category payout_reversal
.
Unsuccessful via NPP (Successfully Processed via DE after channel switching)
If you chose an NPP hybrid account, failed NPP payments are tried via DE, you would expect to receive the following webhooks:
payment.added
debit.cleared
debtor_credit.channel_switched
- (Funds are being sent via the BECS channel)debtor_credit.cleared
- (Funds have been sent to the end customer's bank and marked as cleared on the Zepto dashboard.)
Note: For DC transactions, the cleared webhook does not guarantee that the funds have been settled into the end customer's account. The end customer's bank can take a few hours to settle the funds in the associated bank account.
It has been previously noticed, that for a Direct Credit transaction, the banks can get back to us after a day or two, informing us that the credit to the end customer's account has failed due to various reasons(eg: bank account closed).
In this case, our system will trigger another webhook event with the category payout_reversal
.
Unsuccessful NPP
If you chose a standard Float account (with only NPP transactions or only DE), you would expect to receive the following webhooks:(these webhooks will be fired under the category payout)
payment.added
debit.cleared
debtor_credit.returned
- (Funds will be returned back to your account)
Since the debit side of the transaction was successful, the credit will be reversed back into the original bank account. The below event will then be fired, under the category payout_reversal
.
credit.cleared
- (Funds have been returned to your account)
eg.
For the payment transactions, these are final state webhook events:
debtor_credit.cleared
debtor_credit.returned
credit.cleared
- (category payout_reversal)
In addition, it is also suggested that you configure to the debtor_credit.channel_switched
for transactions via a Hybrid float account.
Unsuccessful Direct Credit
If you chose a standard Float account (with only NPP transactions or only DE), you would expect to receive the following webhooks:
payment.added
debit.cleared
debtor_credit.cleared
debtor_credit.returned
- (Funds will be returned back to your account)
Note: Our system would mark the credit as cleared for a DC transaction based on the nearest available exchange point. The banks can get back to us within one or two business days informing us that the credit failed due to some reason.
In this case, the final debtor_credit.returned
event will be fired.
Since the debit side of the transaction was successful, the credit will be reversed back into the original bank account. The below events will then be fired, under the category payout_reversal
.
credit.cleared
- (Funds have been returned to your account)
Successful Payment Request
While requesting a Payment, your end customers account is being debited and you are the creditor, thus in this case the Webhooks that you need to look for are:
payment_request.added
creditor_debit.cleared
credit.cleared
- (Funds have settled into your nominated bank account)
Unsuccessful Payment Requests
If the banks inform us of an unsuccessful debit before the 2day processing period, the following webhook events should be noted:
payment_request.added
creditor_debit.returned
- (Debited funds were returned back to the end customer's account)credit.voided
- (the credit to your account will be canceled as the debit was unsuccessful)
The final states for a direct debit transaction are:
credit.cleared
creditor_debit.returned
credit.voided
Late Dishonour (Late Return)
A late return occurs when a transaction fails after the standard clearance period. You can find more information regarding late returns here.
The following webhooks will be triggered in the event of a late return:
creditor_debit.cleared
credit.cleared
creditor_debit.returned
The final state of the Late Return will be:
creditor_debit.returned
Manual Late Dishonours (Manual Returns)
Dishonours that occur after the ~3 day clearance period are classified as Manual Late Dishonours.
The OFIs inform us of a failed payment via email, and thus the system will not be able to update the existing status of the debit or credit side of the transaction. As a result, no webhooks will be fired from our end.
The transaction will appear as a normal payment sitting in the cleared
state and you will be notified of any Manual Late Returns via email from our disputes team.
You will also have a record of this in your Zepto account under Recoveries & Returns > Manual Late Returns.
Receiving Funds through PayID
When you receive funds through a PayId, the webhooks that are fired are as follows:
payment_request.approved
creditor_debit.cleared
credit.cleared
Voided Payment
You can also void a payment, by logging in to your Zepto account, navigating to the payment you created, and clicking the cancel button found on the top-right corner of the page. Please be mindful that you can only cancel/void the payment before it is processed.
The webhooks that will be triggered if you successfully cancel the payment before it matures are as follows:
payment.added
debit.voided
debtor_credit.voided
There is also the scenario when your NPP payments fail to process, for example, the customer's bank is not NPP enabled. When this happens, the resulting behavior and webhooks received will depend on the configuration you chose for your account float during setup.
Voided Payment Request
You can also void a payment request, by logging in to your Zepto account, navigating to the payment request you created, and clicking the cancel button found on the top-right corner of the page. Please be mindful that you can only cancel a payment request before it is processed.
The webhooks that will be triggered if you cancel the payment request are as follows:
payment_request.added
payment_request.cancelled
creditor_debit.voided
credit.voided
Feel free to reach out to us via the green bubble on the bottom right of the screen or email us at support@zepto.com.au. Happy to help with all your questions! :)