PayTo Agreement Modifications
This article will guide you on how to manage or modify PayTo Agreements.
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.
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
{
"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"
}
}
Agreement Modification | Initiator/Merchant | Customer |
Cancel | ✓ | ✓ |
Suspend (i.e. Pause agreement) | ✓ | ✓ |
Reactivate (i.e. Resume agreement) | ✓ | ✓ |
Amend | ✓ | ✓ |
Recall amendment | ✓ |
|
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:
{
"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"
}
}
resource_uid | uid will vary per agreement (eg. |
type |
|
code | error code will vary based on reason selected
(eg. |
resource_type |
|
caused_by |
|
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.
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"
}
}
resource_uid | uid will vary per agreement (eg. |
type |
|
resource_type |
|
caused_by |
|
Amendments can be made against certain PayTo Agreement details due to a number of factors such as:
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. |
- 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 |
POST
[[/payto/agreements/{agreement_uid}/amendment]](/reference/post_payto-agreements-agreement-uid-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"
}
}
resource_uid | uid will vary per agreement (eg. |
type |
|
resource_type |
|
caused_by |
|
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. |
{
"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"
}
}
resource_uid | uid will vary per agreement (eg. |
type |
|
resource_type |
|
caused_by |
|
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.
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"
}
}
resource_uid | uid will vary per agreement (eg. |
type |
|
resource_type |
|
caused_by |
|
Updated 4 months ago