5. Agreement Modifications

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.

NOTE: 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

API Documentation: Learn how to cancel a PayTo Agreement

Endpoint

POST /payto/agreements/{agreement_uid}/cancellation

Request Payload

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

Response (202)

No response body.

Webhook

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

resource_uid	uid will vary per agreement (eg. `biz_agreement_G7MQWwkQZIP8vbfH`)
type	`payto_agreement.cancelled`
code	error code will vary based on reason selected (eg. `MD17` is “`initiating_party_requested`”)
resource_type	`payto_agreement`
caused_by	`initiator`

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.

NOTE: 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

API Documentation: Learn how to suspend an agreement

Endpoint

/payto/agreements/{agreement_uid}/suspension

Request Payload

Not applicable

Webhook

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

resource_uid	uid will vary per agreement (eg. `biz_agreement_G7MQWwkQZIP8vbfH`)
type	`payto_agreement.suspended`
code	error code will vary based on reason selected (eg. `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.

NOTE: 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.

API Documentation: Learn how to reactivate a PayTo Agreement

Endpoint

POST /payto/agreements/{agreement_uid}/reactivation

Request Payload

No body.

Response (202)

No body.

Webhook

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

resource_uid	uid will vary per agreement (eg. `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.

NOTE:

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

API Documentation: Learn how to amend a PayTo Agreement

Endpoint

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.

Request Payload

The example below is for a unilateral change of the agreement’s description:

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

Response (202)

No body.

Webhook

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

resource_uid	uid will vary per agreement (eg. `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.

NOTE: A pending amendment can be recalled if it has not been actioned by the end customer (see “Recall Amendment” steps below).

Request Payload

The example below demonstrates a bilateral PayTo amendment by changing the payment frequency:

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

Response (202)

No body.

Webhook

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

resource_uid	uid will vary per agreement (eg. `biz_agreement_G7MQWwkQZIP8vbfH`)
type	`payto_agreement.amended` or `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.

API Documentation: Learn how to recall a PayTo Agreement

Endpoint

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

Request Payload

No body.

Response (202)

No body.

Webhook

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

resource_uid	uid will vary per agreement (eg. `biz_agreement_G7MQWwkQZIP8vbfH`)
type	`payto_agreement.amended_recalled`
resource_type	`payto_agreement`
caused_by	`initiator`