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 settled and failed states 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.settled` `payto_payment.failed` `payto_payment.under_investigation`
`resource_type`	`payto_payment`
`retryable` Only 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
`uid`* (required)	Supplied 64-character unique identifier for payment. This identifier ensures payment uniqueness between integrator systems and Zepto.
`agreement_uid`* (required)	The unique PayTo Agreement UID to validate this payment against.
`amount`* (required)	The amount (in cents) to be collected from the debtor account.
`priority`* (required)	Execution priority of payment. attended payments will be `prioritised` over `unattended` payments. For example: Attended: E-commerce style checkout experiences Unattended: Loan collections
`reference`	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.
`description`	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.
`creditor: party_name`* (required)	The name of the creditor party for this agreement.
`creditor: ultimate_party_name`	The ultimate creditor name for the account, if different than the `party_name`. Defaults to `party_name` if not provided. Most cases, the creditor and ultimate creditor will be the same, in which case this field can be left blank.
`creditor: account_identifier type`* (required)	Select from 5 account identifier types: `bban` (BSB and account number) `alias_email` (Email PayID) `alias_phone` (Phone PayID) `alias_abn` (ABN PayID) `alias_organisation_identifier` (Org. ID PayID)
`creditor: account_identifier value`* (required)	The value of the creditor’s account identifier. In the case of `bban`, this is the account’s branch code and account number separated with a hyphen.
`creditor_reference`	A reference to aid the creditor in reconciling the payment. This is shown on the creditors bank statement.
`last_payment` Required for ‘Balloon’ payment term type.	Indication of a last payment being made towards a balloon payment term type: True False

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`

Creating a PayTo Payment

Overview

🚧

📘

Payment States

📘

Initiating a PayTo Payment

Notable Webhook Fields

Request Payload Parameters

Parameter

Description

Debtor & Creditor Details

Retry a Payment

📘

Request Payload

Response (202)

Notable Webhook Fields