Webhooks & Polling
This article will guide you on how to use webhooks or polling with your API integration.
Webhooks & Polling
Webhooks
Webhooks are used to notify your application of changes to the state of PayTo Agreements and PayTo Payments as and when they are processed through the system.
By subscribing to our webhook events you can monitor the status of each agreement and payment in order to trigger the appropriate next steps.
PayTo Agreement Events
Events | Description |
Activated ( | The Debtor has accepted the Agreement. |
Declined ( | The Debtor has declined the Agreement. |
Expired ( | The Debtor has ignored the Agreement for 5 days. |
Failed | The Agreement creation has failed. |
Cancelled ( | The Debtor or Initiator has cancelled the Agreement. |
Cancellation failed | The Agreement cancellation request has failed. |
Suspended ( | The Debtor or Initiator has suspended (i.e. paused) the Agreement. |
Suspension failed | The Agreement suspension request has failed. |
Reactivated ( | The Debtor or Initiator has reactivated (i.e. resumed) the Agreement. |
Reactivation failed | The Agreement reactivation request has failed. |
Amended ( | The Debtor or Initiator has amended the Agreement. |
Amendment declined ( | The Debtor has declined Agreement amendments initiated by the Initiator. |
Amendment expired ( | The Debtor has ignored the Agreement amendments initiated by the Initiator. |
Amendment failed | The Agreement amendment request has failed. |
Amendment recalled ( | The initiator has recalled an Agreement amendment. |
Amendment recall failed | The Agreement recall request has failed. |
Webhook Sample
{
"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
resource_uid | uid will vary per agreement (eg. |
type (i.e. the event) |
etc. |
resource_type (i.e. the event type) |
|
PayTo Payment Events
Events | Description |
Settled ( | A payment is settled once the funds have successfully cleared and settled from/to the nominated account. |
Failed ( | A payment has failed once the funds were not successfully debited or credited from/to the nominated account. |
Under investigation ( | A payment enters the ‘under investigation’ state when the payer bank is not responding with a final payment status. |
Webhook Sample
{
"data": {
"id": "01888a29-a825-1097-a138-ac96c9125b40",
"body": null,
"type": "payto_payment.settled",
"published_at": "2023-06-05T16:06:05.861+10:00",
"resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"resource_type": "payto_payment"
},
"links": {
"resource": "https://api.sandbox.split.cash/payto/payments/biz_agreement_G7MQWwkQZIP8vbfH"
}
}
Notable Webhook Fields
resource_uid | uid will vary per agreement (eg. |
type (i.e. the event) |
|
resource_type (i.e. the event type) |
|
Polling (Direct Query)
List All PayTo Agreements
A list of successfully submitted PayTo Agreements can be queried directly via API using the endpoint below.
Endpoint
GET
/payto/agreements
Get an Individual PayTo Agreement
An Agreement can be queried directly via API, using the PayTo Agreement UID supplied when creating the Agreement in your original request.
Endpoint
GET
/payto/agreements/{uid}
{
"data": {
"uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"state_reason": null,
"state": "active",
"mms_agreement_id": "d1c34076e5r014301e8b2947d9322222",
"created_at": "2023-06-05T16:12:59+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": "debtor",
"links": {
"self": "https://api.sandbox.split.cash/payto/agreements/biz_agreement_G7MQWwkQZIP8vbfH"
}
}
}
List Agreement History
A list of a single agreement’s history can be queried directly via API using the end point below.
Endpoint
GET /payto/agreements/{agreement_uid}/history
{
"links": {},
"data": [
{
"id": "0188b7ff-1263-bdac-74c9-42ada1a70ad4",
"resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"published_at": "2023-06-14T03:42:06.947Z",
"resource_type": "payto_agreement",
"body": {
"caused_by": "debtor"
},
"type": "payto_agreement.reactivated"
},
{
"id": "0188b7fd-099e-cb2f-23a9-b7bfac0682e1",
"resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"published_at": "2023-06-14T03:39:53.630Z",
"resource_type": "payto_agreement",
"body": {
"reason": {
"code": "MD16",
"title": "Requested By Customer",
"detail": "Agreement/Amendment action requested by the Payer Customer",
"narrative": "My custom description"
},
"caused_by": "debtor"
},
"type": "payto_agreement.suspended"
},
{
"id": "0188b7fc-b325-6176-b843-ff2b47816c3a",
"resource_uid": "biz_agreement_G7MQWwkQZIP8vbfH",
"published_at": "2023-06-14T03:39:31.493Z",
"resource_type": "payto_agreement",
"body": null,
"type": "payto_agreement.activated"
}
]
}
List All PayTo Payments
A list of all successfully submitted PayTo Payments can be queried directly via API using the end point below.
Endpoint
GET /payto/payments
Get an Individual PayTo Payment
A Payment can be queried directly via API, using the PayTo Payment UID supplied when creating the payment in your original request.
Endpoint
GET /payto/payments/{uid}
{
"data": {
"uid": "loancoABC_20230214_G34MQWwkQZIP8vASFH",
"agreement_uid": "ajaysgym_20221222_0007",
"state": "settled",
"amount": 10000,
"last_payment": null,
"priority": "unattended",
"reference": "Loan payment 1 of 4",
"description": "Payment 1 of 4 for Loan #482393",
"creditor": {
"name": "Loan Company ABC Pty Ltd",
"account_identifier": {
"type": "bban",
"value": "123456-98765432"
}
},
"creditor_reference": "PYMNT-1003",
"debtor": {
"ultimate_party_name": "Billie Jean Senior",
"party_name": "Billie Jean Junior",
"account_identifier": {
"type": "bban",
"value": "123456-98765432"
}
},
"failure": null,
"created_at": "2023-01-23T10:52:39+11:00",
"links": {
"self": "https://api.sandbox.split.cash/payto/payments/loancoABC_20230214_G34MQWwkQZIP8vASFH",
"agreement": "https://api.sandbox.split.cash/payto/agreements/ajaysgym_20221222_0007"
}
}
}
Updated 22 days ago