DEVELOPER GUIDE

Creating a PayTo Payment

This article will guide you on how to initiate 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.

High Level Flow

Payment States

Once a PayTo Payment has been accepted in Zepto, it can move through the following states:

State	Description
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
Pending	When a payment's final payment status has not been received after 35 seconds from the successful payment initiation request
	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.

PayTo Payment Lifecycle

Standard Payment

Created
Submitted
Settled or Failed

Delayed Payment

Created
Submitted
Pending
Settled or Failed

Under Investigation

Created
Submitted
Pending
Under Investigation
Settled or Failed

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.pending` `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)

About PayTo Webhooks

Learn more about PayTo webhooks here. These fields and values can be stored in merchant system to map with their customers and automate future payments.

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 (must accurately represent the creditor party and may be the same as the ultimate_party_name)
`creditor: ultimate_party_name`* (required)	The ultimate creditor name (must accurately represent the ultimate creditor party and may be the same as the party_name).
`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.

Failure Codes

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

High Level Flow

Payment States

PayTo Payment Lifecycle

Standard Payment

Delayed Payment

Under Investigation

Initiating a PayTo Payment

Notable Webhook Fields

About PayTo Webhooks

Request Payload Parameters

Parameter

Description

Debtor & Creditor Details

Retry a Payment

Failure Codes

Request Payload

Response (202)

Notable Webhook Fields