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

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

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

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

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:

📘

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

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

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:

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

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