Zepto automatically checks for available balance before attempting to direct debit an account. However, this is only done before the debit is sent to the bank for processing and also requires an active bank connection for the contact that needs to be direct debited.
Another way of pre-checking the customers account for available funds is by enabling the precheck_funds option while you make payment requests using our API endpoint. If there is an active bank connection and this field is set to true, it will ensure that the debtor account is checked for available funds as soon as the payment request is made.
For example, payload to Payment Request endpoint
{
"description": "Visible to both initiator and authoriser",
"matures_at": "2016-12-19T02:10:56.000Z",
"amount": 99000,
"authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"precheck_funds": false,
"metadata":
{
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Notice here, the precheck_funds has been set to false by default and Zepto will only check for available funds before sending them to the bank for processing.
However, in the following example payload, the precheck_funds is set to true and thus the debtor account will be checked for available balance as soon as this request is created.
{
"description": "Visible to both initiator and authoriser",
"matures_at": "2016-12-19T02:10:56.000Z",
"amount": 99000,
"authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"precheck_funds": true,
"metadata":
{
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Please be advised that our response to your system and following behaviour will depend on whether the bank connection has been refreshed recently.
This article discusses the 3 scenarios that can be faced while making a payment request:
Fresh/Refreshed bank connection:
When you have fresh or refreshed bank connections, the Payment Request you have made will have the status: "approved" and will follow either of these two scenarios:
When Successful
If the debtor has enough funds in their bank account while making a Payment Request and precheck_funds is set to be true, the Payment request will be successfully made and if you are subscribed to the webhook events, you should notice the payment_request.approved webhook event. This payment request will now be sent to the bank for processing.
{
"data": [
{
"ref": "PR.22bs",
"payout": {
"amount": 1300,
"matures_at": "2021-04-06T00:00:00Z",
"description": "stale2 connection"
},
"status": "approved",
"created_at": "2021-04-06T04:58:37Z",
"credit_ref": "C.618v",
"matures_at": "2021-04-06T00:00:00Z",
"initiator_id": "87838a5f-28b9-4cbc-9633-5fba462e06f0",
"responded_at": "2021-04-06T04:58:37Z",
"schedule_ref": null,
"authoriser_id": "dd640aa8-1f98-4936-9522-b08f0904d782",
"status_reason": null,
"your_bank_account_id": "87838a5f-28b9-4cbc-9633-5fba462e06f0",
"authoriser_contact_id": "bccf4fe5-9934-4ef1-98f2-7c96e09ee0bf"
}
],
"event": {
"at": "2021-04-06T04:58:37Z",
"who": {
"account_id": "8e0bc9f3-ca9e-4ae9-b148-5b9237822890",
"account_type": "AnyoneAccount",
"bank_account_id": "dd640aa8-1f98-4936-9522-b08f0904d782",
"bank_account_type": "BankAccount"
},
"type": "payment_request.approved"
}
}
When Unsuccessful
However, if the debtor does not have enough fund in their bank account, the Payment request will fail straight away and it will not be added to the system.
You will receive a 400 error with the following error message:
{"errors":"The nominated bank account for this Payment Request has insufficient funds."}
STALE CONNECTION
A bank connection goes stale if it is not refreshed in 30minutes. When making a payment request to such a bank connection will send back payment request-response with status: "unverified"
If Successful
If the payment request is successful, i.e if the requested bank account has enough funds to go ahead with the payment request, you should receive the payment_request.approved webhook event. Example:
{
"data": [
{
"ref": "PR.22bs",
"payout": {
"amount": 1300,
"matures_at": "2021-04-06T00:00:00Z",
"description": "stale2 connection"
},
"status": "unverified",
"created_at": "2021-04-06T04:58:37Z",
"credit_ref": "C.618v",
"matures_at": "2021-04-06T00:00:00Z",
"initiator_id": "87838a5f-28b9-4cbc-9633-5fba462e06f0",
"responded_at": "2021-04-06T04:58:37Z",
"schedule_ref": null,
"authoriser_id": "dd640aa8-1f98-4936-9522-b08f0904d782",
"status_reason": null,
"your_bank_account_id": "87838a5f-28b9-4cbc-9633-5fba462e06f0",
"authoriser_contact_id": "bccf4fe5-9934-4ef1-98f2-7c96e09ee0bf"
}
],
"event": {
"at": "2021-04-06T04:58:37Z",
"who": {
"account_id": "8e0bc9f3-ca9e-4ae9-b148-5b9237822890",
"account_type": "AnyoneAccount",
"bank_account_id": "dd640aa8-1f98-4936-9522-b08f0904d782",
"bank_account_type": "BankAccount"
},
"type": "payment_request.approved"
}
}
If Unsuccessful
When the bank account you are requesting the payment from does not exist or the payment request is cancelled for some reason a payment_request.declined webhook will be fired. Find an example of this webhook below,
Blakes note - Also, should let them know that they will receive a webhook and show them an example response body.
{
"data": [
{
"ref": "PR.233v",
"payout": {
"amount": 13000,
"matures_at": "2021-04-06T00:00:00Z",
"description": "stale2 connection"
},
"status": "declined",
"created_at": "2021-04-08T03:40:20Z",
"credit_ref": null,
"matures_at": "2021-04-06T00:00:00Z",
"initiator_id": "87838a5f-28b9-4cbc-9633-5fba462e06f0",
"responded_at": "2021-04-08T04:41:38Z",
"schedule_ref": null,
"authoriser_id": "569f4597-b64d-477e-83e3-6d63b803778a",
"status_reason": "The nominated bank account for this Payment Request has insufficient funds.",
"your_bank_account_id": "87838a5f-28b9-4cbc-9633-5fba462e06f0",
"authoriser_contact_id": "a42316c3-6b8f-41ff-9562-e7267a00b771"
}
],
"event": {
"at": "2021-04-08T04:41:38Z",
"who": {
"account_id": "5d9d445c-ec48-44f6-a845-9e9b21a7148d",
"account_type": "AnyoneAccount",
"bank_account_id": "569f4597-b64d-477e-83e3-6d63b803778a",
"bank_account_type": "BankAccount"
},
"type": "payment_request.declined"
}
}
NO CONNECTION
If there are no active bank connections to the account while making a payment request, you will receive an error stating the below.
{"errors":"No valid bank connection to precheck funds for this Payment Request."}
Feel free to reach out to our amazing support team via the blue bubble on the bottom right of the screen or email us at support@zepto.com.au.