DEVELOPER GUIDE

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.

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

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:

State	Description
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 Debtor's or Creditor's action
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

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

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

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

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

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

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.

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.

Overview

When a dispute is raised by the bank, Zepto creates the investigation, notifies your platform, and requests merchant action.

Warning

Make sure you submit evidence before the due date. Missing the deadline may result in the case being closed or rejected.

Success

Once accepted, the action request is completed and the dispute workflow progresses accordingly.

Important

Rejecting an action request without the correct review may cause avoidable operational issues.

Tip

Retrieve the investigation first, then inspect the active action request so you can present the right next step to your merchant.