DEVELOPER GUIDE

PayTo Webhooks & Polling

This article will guide you on how to use webhooks or polling with your API integration.

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.

Webhooks

Learn how to subscribe to Webhook events here.

PayTo Agreement Events

Event	Description
Activated (`payto_agreement.activated`)	The Debtor has accepted the Agreement.
Declined (`payto_agreement.declined`)	The Debtor has declined the Agreement.
Expired (`payto_agreement.expired`)	The Debtor has ignored the Agreement for 5 days.
Failed	The Agreement creation has failed.
Cancelled (`payto_agreement.cancelled`)	The Debtor or Initiator has cancelled the Agreement.
Cancellation failed	The Agreement cancellation request has failed.
Suspended (`payto_agreement.suspended`)	The Debtor or Initiator has suspended (i.e. paused) the Agreement.
Suspension failed	The Agreement suspension request has failed.
Reactivated (`payto_agreement.reactivated`)	The Debtor or Initiator has reactivated (i.e. resumed) the Agreement.
Reactivation failed	The Agreement reactivation request has failed.
Amended (`payto_agreement.amended`)	The Debtor or Initiator has amended the Agreement.
Amendment declined (`payto_agreement.amendment_declined`)	The Debtor has declined Agreement amendments initiated by the Initiator.
Amendment expired (`payto_agreement.amendment_expired`)	The Debtor has ignored the Agreement amendments initiated by the Initiator.
Amendment failed	The Agreement amendment request has failed.
Amendment recalled (`payto_agreement.amended_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

Field	Description
`resource_uid`	UID will vary per agreement (e.g. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	(i.e. the event) `payto_agreement.activated`, `payto_agreement.declined`, `payto_agreement.expired`, etc.
`resource_type`	(i.e. the event type) `payto_agreement`

PayTo Payment Events

Event	Description
Settled (`payto_payment.settled`)	A payment is settled once the funds have successfully cleared and settled from/to the nominated account.
Failed (`payto_payment.failed`)	A payment has failed once the funds were not successfully debited or credited from/to the nominated account.
Under investigation (`payto_payment.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

Field	Description
`resource_uid`	UID will vary per agreement (e.g. `biz_agreement_G7MQWwkQZIP8vbfH`)
`type`	(i.e. the event) `payto_payment.settled`, `payto_payment.failed`, or `payto_payment.under_investigation`
`resource_type`	(i.e. the event type) `payto_payment`

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