Creating a PayTo Agreement

Creating a PayTo Agreement

Overview on creating PayTo Agreements with your customer, ultimately enabling payment initiation and the collection of funds in real-time.

PayTo Agreements Overview

To establish a PayTo Agreement, you'll first have to collect your customer's payment data and then submit a request to Zepto's /payto/agreements endpoint with the agreement particulars.

When using a BBAN or PayID as the debtor's account_identifier type, Zepto will perform some checks to make sure that the payer's financial institution supports PayTo, and if so will submit this request onto the NPP's Basic Infrastructure.

❗️

Important note

When using PayID as an account_identifier type, Zepto's Alias Resolution service must be used prior to initiating an agreement creation request.

Read more about the alias resolution endpoint here.

At this point, as long as the financial institutions account type also supports PayTo, your customer should receive a notification from within their financial institution banking portal informing them there is a PayTo Agreement awaiting their authorisation.

Once authorised:

  • the PayTo Agreement will become active
  • Zepto will push a webhook to you containing the authorisation particulars along with the associated PayTo Agreement UID to reconcile with

Agreement States

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

StateDescription
1. PendingThe agreement has been successfully created within Zepto
2. CreatedThe agreement has been successfully created within Zepto and has an associated MMS ID but is awaiting the Debtor’s authorisation
3. Based on Debtor's or Creditor's action
- ActiveThe Debtor has accepted the terms of the Agreement (i.e. authorised)
- DeclinedThe Debtor has declined the terms of the Agreement
- ExpiredThe Debtor has ignored the Agreement for 5 days (expires on day 6)
- CancelledThe Agreement has been cancelled by the Debtor or Creditor/Initiator
- SuspendedThe Agreement has been suspended (i.e. paused) by the Debtor or Creditor/Initiator

📘

The declined, expired and cancelled states are considered final, in that they are irrevocable.


Creating an Agreement

Endpoint: POST /payto/agreements endpoint.

{
  "uid": "biz_agreement_G7MQWwkQZIP8vbfHHHH",
  "purpose": "loan",
  "debtor": {
    "ultimate_party_name": "Billie Jean Senior",
    "party_name": "Billie Jean Junior",
    "account_identifier": {
      "type": "bban",
      "value": "123456-98765432"
    }
  },
  "creditor": {
    "ultimate_party_name": "Billie Jean Senior",
    "party_name": "Billie Jean Junior",
    "account_identifier": {
      "type": "bban",
      "value": "123456-98765432"
    }
  },
  "initiator": {
    "name": "Jane's Flowers",
    "legal_name": "Blossoming Flowers Pty Ltd",
    "abn": "56192755287"
  },
  "description": "Payment plan for loan #1234",
  "resolution_requested_before": "2023-06-09T12:34:56Z",
  "validity_start_date": "2023-06-05",
  "validity_end_date": "2023-12-31",
  "payment_terms": {
    "type": "fixed",
    "frequency": "monthly",
    "amount": 10000,
    "count": 1
  }
 }
{
    "data": {
        "uid": "biz_agreement_G7MQWwkQZIP8vbfH",
        "state_reason": null,
        "state": "pending",
        "mms_agreement_id": null,
        "created_at": "2023-06-05T15:50:58+10:00",
        "purpose": "loan",
        "resolution_requested_before": "2023-06-09T12:34:56Z",
        "payment_terms": {
            "type": "fixed",
            "frequency": "monthly",
            "count": 1,
            "max_amount": null,
            "amount": 10000,
            "first_payment_amount": null,
            "last_payment_amount": null,
            "first_payment_date": null,
            "last_payment_date": null
        },
        "debtor": {
            "party_name": "Billie Jean Junior",
            "ultimate_party_name": "Billie Jean Senior",
            "account_identifier": {
                "type": "bban",
                "value": "123456-98765432"
            }
        },
        "creditor": {
            "party_name": "Billie Jean Junior",
            "ultimate_party_name": "Billie Jean Senior",
            "account_identifier": {
                "type": "bban",
                "value": "123456-98765432"
            }
        },
        "initiator": {
            "name": "Jane's Flowers",
            "legal_name": "Blossoming Flowers Pty Ltd",
            "abn": "56192755287"
        },
        "description": "Payment plan for loan #1234",
        "validity_start_date": "2023-06-05",
        "validity_end_date": "2023-12-31",
        "state_caused_by": "initiator",
        "links": {
            "self": "https://api.sandbox.split.cash/payto/agreements/biz_agreement_G7MQWwkQZIP8vbfH"
        }
    }
}
{
  "data": {
    "id": "01888a1b-cf5c-94d9-eea6-be9209e47197",
    "body": {
      "mms_agreement_id": "d1c34076e5r014301e8b2947d9322222"
    },
    "type": "payto_agreement.activated",
    "published_at": "2023-06-05T15:50:58.396+10:00",
    "resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
    "resource_type": "payto_agreement"
  },
  "links": {
    "resource": "https://api.sandbox.split.cash/payto/agreements/biz_agreement_G7MQWwkQZIP8vbfH"
  }
}

Notable Webhook Fields

FieldDescription
resource_uiduid will vary per agreement
(eg. biz_agreement_G7MQWwkQZIP8vbfH)
typepayto_agreement.activated
resource_typepayto_agreement

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 creating a new Agreement, there are a number of parameters that must be provided in order to outline the specific payment arrangement between you and your customer.

Parameter

Description

uid* (required)

The supplied unique 64-character identifier for the Agreement.

This identifier ensures agreement uniqueness between integrator systems and Zepto.

purpose* (required)

Select from 12 purposes to define the nature of the PayTo Agreement with your customer:

  • mortgage

  • utility

  • loan

  • dependant_support

  • gambling

  • retail

  • salary

  • personal

  • government

  • pension

  • tax

  • other

The purpose should reflect the reason the PayTo agreement is being proposed.

debtor: ultimate_party_name

The ultimate debtor name for the account, if different than the party_name.

Defaults to party_name if not provided.

Most cases, the debtor and ultimate debtor will be the same, in which case this field can be left blank.

debtor: party_name* (required)

The name of the debtor party for this agreement.

debtor: 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)

Please note: There is a limit of 6 agreement creation attempts within 24 hours per debtor account.

debtor: account_identifier value* (required)

The value of the debtor’s account identifier.

In the case of bban, this is the account’s branch code and account number separated with a hyphen.

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: party_name* (required)

The name of the creditor party for this agreement.

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.

initiator: name

The name of the initiating party for this agreement displayed to the end customer by their financial institution.

The values provided in initiator will be ignored unless the merchant has been approved as a third-party payment processor.

initiator: legal_name

The legal name of the initiating party for this agreement.

initiator: abn

The Australian Business Number (ABN) of the initiating party for this agreement.

description* (required)

The reason for the Agreement, as narrative text (1-140 characters).

resolution_requested_before

Requested resolution (accept/decline) deadline for this agreement. It will be provided in any notification sent to the debtor. Value must be an ISO8601 date-time in UTC timezone.

This time is for informational purposes only and does not affect the expiry time which occurs after 5 days of inaction by the debtor.

validity_start_date

Start date for the validity of the agreement.

If specified, the agreement will be valid from 00:00:00 Australia Sydney time on the specified date. If no date is specified, the current date will be populated.

validity_end_date

End date of the validity of the agreement.

If specified, the agreement will be valid until 23:59:59.999 Australia Sydney time on this date.

If the agreement is in an active state 2 weeks after the specified validity end date, Zepto will automatically cancel the agreement (Reason code: MD20).

payment_terms: type* (required)

The type of payment terms must be on of the following:

  • fixed: Payment amount is fixed

  • used-based: Payment amount is based on usage

  • variable: Payment amount is variable

  • balloon: Recurring payment amount is fixed with a large final payment amount

payment_terms: frequency* (required)

The frequency at which payments will be made. Frequency can be used in conjunction with ‘count’ to allow more than one payment per period.

The frequency must be one of the following:

  • adhoc: A payment on request or as necessary

  • daily: A payment daily

  • weekly: A payment once per week

  • fortnightly: A payment every 2 weeks

  • monthly: A payment once per month

  • quarterly: A payment every 3 months

  • semi_annual: A payment twice per year

  • annual: A payment once per year

payment_terms: amount* (required)

Required for 'Fixed' and ‘Balloon’ payment term types.

The fixed amount to be debited from the payer's account.

payment_terms: count

The number of payments allowed per frequency period:

  • If no Count is provided, one payment per frequency period will be allowed

  • If no Count is provided with the Ad Hoc frequency, the number of payments allowed will be unlimited

payment_terms: max_amount

Applicable for ‘Variable’ and ‘Usage based’ payment term types.

The maximum allowed payment amount, in cents.

payment_terms: first_payment_amount

Applicable to ‘Balloon’ payment term type only.

The fixed amount for the first payment to be debited from the payer's account.

payment_terms: last_payment_amount

Applicable to ‘Balloon’ payment term type only.

The fixed amount for the last payment to be debited from the payer's account.

payment_terms: first_payment_date

Applicable to ‘Balloon’ payment term type only.

The date the first payment will be initiated for agreement.

payment_terms: last_payment_date

Applicable to ‘Balloon’ payment term type only.

The date the last payment will be initiated for agreement.


Debtor & Creditor Details

Zepto supports PayTo Agreements using both BBAN (BSB and Account number) and PayID (i.e. email, phone, ABN, and organisation identifier).


PayTo Alias Resolution

Utilise Zepto's PayTo Alias Resolution service to validate the name associated with a PayID:

Alias Resolution

Initiator Details

If your account has been approved as a Third Party Processor (TPP), your merchant's details should be supplied in the initiator name, legal_name, and abn fields. These will be passed through and made visible to the end customer by their financial institution.

Otherwise, your registered Zepto account details will be used to populate these fields and any supplied values will be ignored.


Payment Terms

The payment_terms provided outline the specific attributes of the goods and services purchase being agreed to.

NOTE: Required fields vary depending on the payment term type.

Once accepted, Zepto will validate all payment attempts made against this Agreement to ensure that it conforms to the PayTo Agreement's terms; payments that do not will be rejected.

Payment Terms: Frequency

The examples provided below reference a validity_start_date of Wednesday October 4th, 2023 (04/10/2023).

Frequency

Details

adhoc

daily

Valid until 23:59:59.999 Australia Sydney time the same day.

Example: The next period begins at 00:00:00 Australia Sydney time each day.

weekly

Valid until 23:59:59.999 Australia Sydney time on the 7th day.

Example: The next period begins at 00:00:00 Australia Sydney time on 11th of October, 2023.

fortnightly

Valid until 23:59:59.999 Australia Sydney time on the 14th day.

Example: The next period begins at 00:00:00 Australia Sydney time on 18th of October, 2023.

monthly

Valid for the month, up until 23:59:59.999 Australia Sydney time the day before the day noted in the validity_start_date.

Example: The next period begins at 00:00:00 Australia Sydney time on 4th of November, 2023.

quarterly

Valid for 3 months, up until 23:59:59.999 Australia Sydney time the day before the day noted in the validity_start_date.

Example: The next period begins at 00:00:00 Australia Sydney time on 4th of January, 2024.

semi_annual

Valid for 6 months, up until 23:59:59.999 Australia Sydney time the day before the day noted in the validity_start_date.

Example: The next period begins at 00:00:00 Australia Sydney time on 4th of April, 2024.

annual

Valid for 12 months, up until 23:59:59.999 Australia Sydney time the day before the day noted in the validity_start_date.

Example: The next period begins at 00:00:00 Australia Sydney time on 4th of October, 2024.

📘

Edge case

For periods starting at the end of a month with 31 days, when calculating a period during a shorter month, the end of the shorter month will be the period end.