Webhooks & Polling

Webhooks & Polling

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

card icon

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.

Learn how to subscribe to Zepto's webhooks here

PayTo Agreement Events

Events

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

resource_uid

uid will vary per agreement

(eg. biz_agreement_G7MQWwkQZIP8vbfH)

type

(i.e. the event)

payto_agreement.activated or

payto_agreement.declined or

payto_agreement.expired

etc.

resource_type

(i.e. the event type)

payto_agreement



PayTo Payment Events

Events

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

resource_uid

uid will vary per agreement

(eg. biz_agreement_G7MQWwkQZIP8vbfH)

type

(i.e. the event)

payto_payment.settled or

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