DEVELOPER GUIDE

PayTo Agreement Modifications

This article will guide you on how to manage or modify PayTo Agreements.

Once an agreement has been successfully created and authorised, both you and your customer will be able to perform the following actions against it:

Agreement Modification	Initiator / Merchant	Customer
Cancel	✓	✓
Suspend (i.e. Pause agreement)	✓	✓
Reactivate (i.e. Resume agreement)	✓	✓
Amend	✓	✓
Recall amendment	✓

The following page steps through the agreement modifications that can be actioned by the initiator.

Cancelling a PayTo Agreement

As the initiator, you may Cancel a PayTo Agreement at any time. This will update the Agreement's state to cancelled where it will have no further use.

A cancelled PayTo Agreement is final, and can no longer be used to collect funds. If this was done in error, a new PayTo Agreement will need to be established with your customer where their consent will be required.

For the Agreement that requires cancellation, just supply the Agreement UID that you wish to cancel, the specific reason why, and an optional free text description. Examples of a few of the main ones are:

suspected_fraudulent
contract_expired
regulatory
no_answer

Endpoint

POST /payto/agreements/{agreement_uid}/cancellation

{
  "reason": "initiating_party_requested",
  "narrative": "Created in error"
}

No response body

{
  "data": {
    "id": "01888a1d-b126-fd11-1259-ee48fdbf683e",
    "body": {
      "reason": {
        "code": "MD17",
        "title": "Requested By Initiating Party",
        "detail": "Cancellation/amendment requested by the creditor or by the initiating party",
        "narrative": "Created in error"
      },
      "caused_by": "initiator"
    },
    "type": "payto_agreement.cancelled",
    "published_at": "2023-06-05T15:53:01.734+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

Agreement Modification	Initiator / Merchant	Customer
Cancel	✓	✓
Suspend (i.e. Pause agreement)	✓	✓
Reactivate (i.e. Resume agreement)	✓	✓
Amend	✓	✓
Recall amendment	✓

Suspending a PayTo Agreement

You may choose to Suspend an Agreement at any time. Just supply the Agreement UID that you wish to suspend, the specific reason why, and an optional free text description.

A suspended PayTo Agreement cannot be used to collect funds.

For the Agreement that requires a suspension, just supply the Agreement UID that you wish to suspend, the specific reason why, and an optional free text description. Examples of a few of the main ones are:

suspected_fraudulent
contract_expired
regulatory
no_answer

Endpoint

POST /payto/agreements/{agreement_uid}/suspension

{
  "reason": "customer_requested", 
  "narrative": "My custom reason"
   "sandbox": {
    "simulate": "successful_suspension"
  },
}

{
  "data": {
    "id": "01889899-efeb-b8d4-988e-d86d3c21573b",
    "body": {
      "reason": {
        "code": "MD17",
        "title": "Requested By Initiating Party",
        "detail": "Cancellation/amendment requested by the creditor or by the initiating party",
        "narrative": "Suspending agreement"
      },
      "caused_by": "initiator"
    },
    "type": "payto_agreement.suspended",
    "published_at": "2023-06-08T11:23:25.291+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 (e.g. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_agreement.suspended`
`code`	Error code will vary based on reason selected (e.g. `MD17` is `initiating_party_requested`)
`resource_type`	`payto_agreement`
`caused_by`	`initiator`

Reactivate a PayTo Agreement

You may reactivate a suspended PayTo Agreement where you were the original initiator of the suspension.

You may NOT reactivate a Suspended PayTo Agreement where Zepto or your customer was the initiator of the original suspension.

For the Agreement that requires a reactivation, just supply the Agreement UID that you wish to reactivate in the request URL.

Endpoint

POST /payto/agreements/{agreement_uid}/reactivation

Not applicable

No body

{
  "data": {
    "id": "018898a7-6980-978d-0da8-07212b988470",
    "body": {
      "caused_by": "initiator"
    },
    "type": "payto_agreement.reactivated",
    "published_at": "2023-06-08T11:38:08.384+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 (e.g. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_agreement.reactivated`
`resource_type`	`payto_agreement`
`caused_by`	`initiator`

Amend a PayTo Agreement

Amendments can be made against certain PayTo Agreement details due to a number of factors such as:

changes to the Goods and Services arrangement
bank account detail changes
name changes
etc.

Depending on the information being altered, the amendments are classified as one of the following types:

Amendment Type	Description
Unilateral action (i.e. immediate)	These changes will be accepted by the NPP immediately.
Bilateral action (i.e. requires authorisation)	These changes will send a notification to your customer to request their authorisation before the changes take effect.
Not permitted	These fields cannot be changed. Should these fields need to be changed, the agreement would have to be cancelled and a new one issued and authorised in its place.

Amendment Type

Description

Unilateral action

(i.e. immediate)

These changes will be accepted by the NPP immediately.

Bilateral action

(i.e. requires authorisation)

These changes will send a notification to your customer to request their authorisation before the changes take effect.

Not permitted

These fields cannot be changed.

Should these fields need to be changed, the agreement would have to be cancelled and a new one issued and authorised in its place.

If an immediate element is bundled into a request with an element that requires authorisation, the entire amendment request will require authorisation.

You may choose to perform separate requests to distinguish between unilateral and bilateral updates. Only 1 amendment can be pending at any 1 time

The table below lists what data can and cannot be amended by the initiator and customer as well as their amendment type:

Agreement Element	Initiator / Merchant	Customer
purpose	Not permitted	Not permitted
description	Immediate	Not permitted
resolution_requested_before	Not permitted	Not permitted
validity_start_date	Not permitted	Not permitted
initiator.name	Immediate	Not permitted
initiator.legal_name	Immediate	Not permitted
initiator.abn	Immediate	Not permitted
validity_end_date	If set, requires authorisation	Not permitted
payment_terms.type	Requires authorisation	Not permitted
payment_terms.frequency	Requires authorisation	Not permitted
payment_terms.count	Requires authorisation	Not permitted
payment_terms.amount	Requires authorisation	Not permitted
payment_terms.max_amount	Requires authorisation	Not permitted
payment_terms.first_payment_date	Requires authorisation	Not permitted
payment_terms.last_payment_date	Requires authorisation	Not permitted
payment_terms.first_payment_amount	Requires authorisation	Not permitted
payment_terms.last_payment_amount	Requires authorisation	Not permitted
purpose	Not permitted	Not permitted
debtor.party_name	Not permitted	Immediate
debtor.ultimate_party_name	Not permitted	Immediate
debtor.account_identifier.type	Not permitted	Immediate
debtor.account_identifier.value	Not permitted	Immediate

Endpoint

POST [[/payto/agreements/{agreement_uid}/amendment]](/reference/post_payto-agreements-agreement-uid-amendment)

Unilateral PayTo Amendment

A unilateral PayTo Amendment is where an Agreement action does not require the authorisation from the other party resulting in immediate changes to the PayTo agreement.

{
  "changes": {
    "description": "Update agreement description here"
  }
}

No body

{
  "data": {
    "id": "018898f0-34a5-3693-4a5a-e231cc64659b",
    "body": {
      "changes": {
        "description": "Changing the description for a unilateral amendment"
      },
      "caused_by": "initiator"
    },
    "type": "payto_agreement.amended",
    "published_at": "2023-06-08T12:57:38.981+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 (e.g. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_agreement.amended`
`resource_type`	`payto_agreement`
`caused_by`	`initiator`

Bilateral PayTo Amendment

A bilateral PayTo Amendment is where an Agreement action requires authorisation from the other party. In this instance, a webhook notifications with one of the following results can be expected:

Amendment Result	Description
Amendment approved	The end customer has approved the agreement amendment. If approved by the customer, the Active Agreement will be updated with the new terms which will take effect immediately.
Amendment declined	The end customer has declined the agreement amendment. If declined by the customer, the Active Agreement will not be updated, and the existing terms will remain in effect.
Amendment expired	The end customer has ignored the amendment for longer than 5 days. If ignored by the customer, the Active Agreement's existing terms will continue to remain in effect.

Amendment Result

Description

Amendment approved

The end customer has approved the agreement amendment.

If approved by the customer, the Active Agreement will be updated with the new terms which will take effect immediately.

Amendment declined

The end customer has declined the agreement amendment.

If declined by the customer, the Active Agreement will not be updated, and the existing terms will remain in effect.

Amendment expired

The end customer has ignored the amendment for longer than 5 days.

If ignored by the customer, the Active Agreement's existing terms will continue to remain in effect.

{
  "changes": {
    "payment_terms": {
      "frequency": "weekly"
    }
  }
}

No body

{
  "data": {
    "id": "018898fe-7c1c-5ac3-d175-0ca198783cd6",
    "body": {
      "changes": {
        "payment_terms": {
          "frequency": "weekly"
        }
      },
      "caused_by": "initiator"
    },
    "type": "payto_agreement.amended",
    "published_at": "2023-06-08T13:13:14.780+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 (e.g. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_agreement.amended`, `payto_agreement.amendment_declined`, or `payto_agreement.amendment_expired`
`resource_type`	`payto_agreement`
`caused_by`	`initiator`

Recall a PayTo Agreement Amendment

You may recall an amendment to a PayTo Agreement before it has been actioned by the customer. Once the amendment has been recalled, a new amendment can be created as only 1 pending amendment can ever be in flight

For the Agreement that requires a recalled amendment, just supply the Agreement UID that you wish to reactivate in the request URL.

Endpoint

POST /payto/agreements/{agreement_uid}/amendment/recall

Not applicable

No body

{
  "data": {
    "id": "0188b33d-0e22-83c9-6efd-a975ea236f05",
    "body": null,
    "type": "payto_agreement.amendment_recalled",
    "published_at": "2023-06-13T15:31:43.010+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 (e.g. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	`payto_agreement.amended_recalled`
`resource_type`	`payto_agreement`
`caused_by`	`initiator`