4. Creating a PayTo Payment

After a PayTo Agreement has been accepted by your customer, you'll be able to initiate PayTo payment requests to collect funds in real-time.

Payment initiations are a relatively straightforward process:

You, as the Payee, make a request to Zepto’s PayTo Payments endpoint.

The payment attributes provided should align with the terms of the authorised PayTo Agreement or the payment will be rejected immediately. If validation is successful, the payment will be submitted to the NPP.

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

NOTE: 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 by Zepto, it will move through the following states:

Created: A payment request is in a created state upon successful submission of a PayTo Payment (i.e. 201 response from Zepto)
Submitted: When a payment has been submitted onto the NPP’s basic infrastructure and is awaiting a response from the payer participant
Based on the result, the payment will move to one of the following states:
- Settled: A payment is settled once the funds have successfully been debited and credited to the nominated accounts
  or
- Failed: A payment can fail for a variety of reasons that will be disclosed inside of the payment failed webhook
  or
- 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.

NOTE: The settled and failed states are considered final, in that they are irrevocable.

Creating a PayTo Payment

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 payment initiations using both BBAN (BSB and Account number) and PayID (i.e. email, phone, ABN, and organisation identifier).

Initiating a PayTo Payment

This example demonstrates a payment against an Active Agreement that successfully settles.

Endpoint

POST /payto/payments

Request Payload

{
  "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": "deposits@companyname.com.au"
    }
  },
  "creditor_reference": PYMNT-1003,
  "last_payment": false,
}

Response

Upon submission, a synchronous response will show one of the following:

Successful: 201 response
Failed:
- 400: Bad request
- 422: Unprocessable entity

201: Successful Response Sample

{
    "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": "deposits@companyname.com.au"
            }
        },
        "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"
        }
    }
}

400: Bad Request Sample

{
  "errors": [
    {
      "title": "Validation Failed",
      "detail": "The value for `invalid_key` is not allowed"
    }
  ]
}

422: Unprocessable Entity Sample

When a payment request is submitted and fails validation (eg. payment request falls outside of customer authorised PayTo Agreement terms), Zepto will return a (422) response detailing any errors responsible for the invalid request.

{
  "errors": [
    {
      "code": "ZPUNP02",
      "title": "Invalid creditor account",
      "detail": "The given creditor account cannot accept funds via NPP"
    }
  ]
}

See full list of unprocessable entity codes

Webhook: Settled Sample

NOTE: Webhooks are only available for PayTo Payment requests that have received a 201 response from Zepto (i.e. successful request).

{
  "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"
  }
}

Webhook: Failed Sample

{
  "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

`resource_uid`	uid will vary per agreement (eg. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_payment.settled` `payto_payment.failed` `payto_payment.under_investigation`
`retryable` Only appears for failed payments.	`true` (i.e. payment retry available) `false` (i.e. payment retry not available)
`resource_type`	`payto_payment`

Learn more about PayTo webhooks here.

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.

NOTE: 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

Request Payload

Not applicable

Response (202)

Not applicable

Webhook: Settled Sample

{
  "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

`resource_uid`	uid will vary per agreement (eg. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_payment.settled`
`resource_type`	`payto_payment`

Payment States

Creating a PayTo Payment

Parameters

Parameter

Description

Debtor & Creditor Details

Initiating a PayTo Payment

Endpoint

Request Payload

Response

201: Successful Response Sample

400: Bad Request Sample

422: Unprocessable Entity Sample

Webhook: Settled Sample

Webhook: Failed Sample

Notable Webhook Fields

Retry a Payment

Endpoint

Request Payload

Response (202)

Webhook: Settled Sample

Notable Webhook Fields