3. Creating a PayTo Agreement

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.

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

Pending: The agreement has been successfully created within Zepto
Created: The agreement has been successfully created within Zepto and has an associated MMS ID but is awaiting the Debtor’s authorisation
Based on the Debtor or Creditor's action, the agreement will move to one of the following states:
- Active: The Debtor has accepted the terms of the Agreement (i.e. authorised)
- Declined: The Debtor has declined the terms of the Agreement
- Expired: The Debtor has ignored the Agreement for 5 days (expires on day 6)
- Cancelled: The Agreement has been cancelled by the Debtor or Creditor/Initiator
- Suspended: The Agreement has been suspended (i.e. paused) by the Debtor or Creditor/Initiator

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

Creating an Agreement

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 or suspended 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.

Create an Agreement

Endpoint

POST /payto/agreements/

Request Payload

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

Response [201]

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

Webhook

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

Field	Description
`resource_uid`	uid will vary per agreement (eg. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_agreement.activated`
`resource_type`	`payto_agreement`

Learn more about PayTo webhooks here

Next Steps

Once a PayTo Agreement has been Accepted by your customer (i.e. is in an ‘Active’ state), the following actions can be performed against it:

Initiate PayTo Payments
Amend agreement
Recall amendment to agreement
Cancel agreement
Suspend agreement
Reactivate agreement

Learn more about creating PayTo Payments here

Learn more about managing PayTo Agreements here