Need to Know

• Subscribe to changes in Paytron accounts using the create subscription endpoint.
• You need to create a subscription for each resource type in the account (e.g. payments, and bills).
• Resource types match those available as options for Paytron Links (always lowercase, always plural).
• Any event in the system for that resource will be sent to your specified callback URL.
• All event messages will include the full resource data, matching the API contract for that resource type.
• Delivery will be retried with a linear back-off up to 5 times before it's considered failed.

How to Subscribe

Paytron manages subscription at a resource level, with every type of resource (e.g. bills or payments) requiring its own distinct subscription.

Each subscription specifies a callback URL for delivery of webhook messages, along with its own unique client secret. To create a new webhook subscription, send a PUT request to the subscriptions/{resourceType} endpoint.

Subscriptions can share a callback URL, or can have their own unique callback URL.

When successfully creating a new subscription, or replacing an old one, you will receive a unique subscriptionSecret. Make sure you store this securely in your system as you will need it to verify request signatures later.

Receiving Webhook Events

Webhook events will be sent to you any time a subscribed resource is added, modified or removed from the Paytron system.

Each webhook event will contain an event name, indicating what happened, as well as the full data for that resource if it still exists after the operation.

Paytron will attempt delivery of the message 5 times, with a linear back-off, before marking delivery as failed. If you believe you have missed an event, you can use the list events endpoint to retrieve it.

Webhook Event Format

All Paytron webhooks have the same top level JSON structure, with the affected resource provided in the data parameter. The format will match the API contract for the specified resource type.

Note: Paytron Links are not available to webhook events.

The event looks as follows:

{
    "accountId": "1245-6789",
    "resourceType": "payments",
    "resourceId": "1234-5678", // i.e. the payment ID or bill ID
    "eventName": "payment_updated",
    "messageId": "1234-5678",
    "sentAt": "2023-04-11T11:52:12.875Z",
    "data":{
      // API version of your resource
    }
}

Available Events

Payment Events

The table below lists all currently supported payment events, available on resource type payments:

Bill Events

The table below lists all currently supported bills events, available on the resource type bills: