Creating a PayTo Payment
This article will guide you on how to initiate a PayTo payment.
Creating a PayTo Payment
Overview
In order to initiate a PayTo payment, you must have:
- An Active PayTo Agreement with the payer.
- The payment attributes provided should align with the terms of the authorised PayTo Agreement.
Once the NPP has received the PayTo Payment Initiation request, we should expect to find out the final payment status within a few seconds. Please note that the NPP has SLAs built in to around 30 seconds for any outliers.
Once Zepto receives the final payment status report from the NPP, we will trigger a payment status webhook to your application containing the outcome:
- Payment Successful; OR
- Payment Failed
Once a PayTo Payment has been submitted onto the NPP Basic Infrastructure, it is irrevocable and can not be cancelled; funds are cleared & settled between the debtor and creditor account in real-time.
Payment States
Once a PayTo Payment has been accepted in Zepto, it can move through the following states:
| State | Description |
|---|---|
| 1. Created | A payment request is in a created state upon successful submission of a PayTo Payment (i.e. 201 response from Zepto) |
| 2. Submitted | When a payment has been submitted onto the NPP’s basic infrastructure and is awaiting a response from the payer participant |
| 3. | Based on the result, the state will then change to one of the following |
| - Settled | A payment is settled once the funds have successfully been debited and credited to the nominated accounts |
| - Failed | A payment can fail for a variety of reasons that will be disclosed inside of the payment failed webhook |
| - Under Investigation | This state indicates an issue where the final payment status (i.e. whether the payment was accepted or rejected) was not received from the payer participant and requires manual intervention from Zepto to resolve. Please note: Zepto employs an automated process in effort to resolve the status of these payments with the payer participant prior to converting the payment to the under_investigation state. |
The
settledandfailedstates are considered final, in that they are irrevocable.
Initiating a PayTo Payment
Endpoint: POST /payto/payments endpoint.
{
"uid": "biz_20221231_G7MQWwkQZIP8vbfH",
"agreement_uid": "Agreement_00012345",
"amount": 2495,
"priority": "unattended",
"reference": "INVOICE #1003",
"description": "Payment 1 of 6 for Zeptinghouse Smart Fridge 300L",
"creditor": {
"party_name": "Jane Smith",
"ultimate_party_name": "Jane Smith",
"account_identifier": {
"type": "alias_email",
"value": "[email protected]"
}
},
"creditor_reference": PYMNT-1003,
"last_payment": false,
}
{
"data": {
"uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"agreement_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"state": "created",
"amount": 10000,
"last_payment": null,
"priority": "attended",
"reference": "INVOICE #1003",
"description": "Payment 1 of 6 for Zeptinghouse Smart Fridge 300L",
"creditor": {
"party_name": "Billie Jean Junior",
"ultimate_party_name": "Billie Jean Senior",
"account_identifier": {
"type": "alias_email",
"value": "[email protected]"
}
},
"creditor_reference": "PYMNT-1003",
"debtor": {
"ultimate_party_name": "Billie Jean Senior",
"party_name": "Billie Jean Junior",
"account_identifier": {
"type": "bban",
"value": "123456-98765432"
}
},
"failure": null,
"created_at": "2023-06-05T16:13:21+10:00",
"links": {
"self": "https://api.sandbox.split.cash/payto/payments/biz_agreement_G7MQWwkQZIP8vbfH",
"agreement": "https://api.sandbox.split.cash/payto/agreements/biz_agreement_G7MQWwkQZIP8vbfH"
}
}
}
{
"data": {
"id": "0188b886-f902-9df5-571b-81a7908f053e",
"body": null,
"type": "payto_payment.settled",
"published_at": "2023-06-14T16:10:33.346+10:00",
"resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"resource_type": "payto_payment"
},
"links": {
"resource": "https://api.sandbox.split.cash/payto/payments/biz_agreement_G7MQWwkQZIP8vbfH"
}
}
{
"data": {
"id": "0188b886-15d0-70ca-acb1-06a008519919",
"body": {
"failure": {
"code": "AM04",
"title": "Insufficient Funds",
"detail": "The specified Payer Customer Account has insufficient funds",
"retryable": true
}
},
"type": "payto_payment.failed",
"published_at": "2023-06-14T16:09:35.184+10:00",
"resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"resource_type": "payto_payment"
},
"links": {
"resource": "https://api.sandbox.split.cash/payto/payments/biz_agreement_G7MQWwkQZIP8vbfH"
}
}
Notable Webhook Fields
| Field | Description |
|---|---|
resource_uid | uid will vary per agreement (eg. biz_agreement_G7MQWwkQZIP8vbfH) |
type | payto_payment.settledpayto_payment.failedpayto_payment.under_investigation |
resource_type | payto_payment |
retryableOnly appears for failed payments. | true (i.e. payment retry available)false (i.e. payment retry not available) |
Learn more about PayTo webhooks here.
Request Payload Parameters
When initiating a PayTo payment, you'll need to specify the following request parameters:
Parameter |
Description |
|
|
Supplied 64-character unique identifier for payment. This identifier ensures payment uniqueness between integrator systems and Zepto. |
|
|
The unique PayTo Agreement UID to validate this payment against. |
|
|
The amount (in cents) to be collected from the debtor account. |
|
|
Execution priority of payment. attended payments will be
For example:
|
|
|
Supplied 35-character free-form text for reconciliation purposes.
Typically this field will be shown to both parties on bank statements, however, the debtor can control this via the agreement as the agreement's reference takes precedence over this field when it has been set by the debtor. |
|
|
Supplied 280-character free-form text for the matching/reconciliation of a transaction.
Similar to the reference field, this can be shown on both parties' bank statements. The difference is that this description can be a longer string and banks will display this separately from the reference. |
|
|
The name of the creditor party for this agreement. |
|
|
The ultimate creditor name for the account, if different than the
Defaults to
Most cases, the creditor and ultimate creditor will be the same, in which case this field can be left blank. |
|
|
Select from 5 account identifier types:
|
|
|
The value of the creditor’s account identifier.
In the case of |
|
|
A reference to aid the creditor in reconciling the payment.
This is shown on the creditors bank statement. |
|
Required for ‘Balloon’ payment term type. |
Indication of a last payment being made towards a balloon payment term type:
|
Debtor & Creditor Details
Zepto supports PayTo Agreements using both BBAN (BSB and Account number) and PayID (i.e. email, phone, ABN, and organisation identifier).
Retry a Payment
In the event that a payment has failed for retryable reasons (i.e. payto_payment.failed and “retryable”: true), you’ll be able to retry a payment within the existing agreement.
Retryable reasons include the following error codes:
AB01, AB02, AB03, AB04, AB08, AC06, AG07, AM04, AM21, FF10, NARR, SL13, SL14, TD03, and TM01.
See failure code descriptions here.
Payments may be retried up to 10 times while within the related agreement's validity begin and end dates. Additionally, payments can only be retried 5 times within 24 hours.
Endpoint POST
[/payto/payments/{payment_uid}/retry](/reference/post_payto-payments-payment-uid-retry)
Request Payload
Not applicable
Response (202)
Not applicable
{
"data": {
"id": "0188b868-c420-52e0-1edc-6a534c188079",
"body": null,
"type": "payto_payment.settled",
"published_at": "2023-06-14T15:37:33.728+10:00",
"resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"resource_type": "payto_payment"
},
"links": {
"resource": "https://api.sandbox.split.cash/payto/payments/biz_agreement_G7MQWwkQZIP8vbfH"
}
}
Notable Webhook Fields
| Field | Description |
|---|---|
resource_uid | uid will vary per agreement (eg. biz_agreement_G7MQWwkQZIP8vbfH) |
type | payto_payment.settled |
resource_type | payto_payment |
Updated 29 days ago