Therius Webhook Events Catalog and Payloads

This page lists every event type Therius delivers to a configured webhook endpoint. Subscribe to a subset under Developers → Webhooks, or leave the selection empty to receive all of them. See Webhooks Overview for delivery, retry, and signature-verification details.

Payment events

Payment event payloads use this envelope:

{
  "event": "payment.captured",
  "environment": "production",
  "created_at": "2026-08-29T12:00:00Z",
  "data": {
    "payment_id": "b1f2...",
    "transaction_id": "t_9a8b...",
    "order_code": "ORDER-001",
    "payment_code": "PAY-abc123",
    "merchant_id": 42,
    "status": "captured",
    "amount": 1999,
    "currency": "USD",
    "exponent": 2,
    "authorization_code": "OK123"
  }
}

When the payment saved a card (tokenize: true), data.token carries it as { "id": "vt_...", "expirationDate": "...", "tokenCreationReference": "..." }, the same object as the purchase response. A card on an asynchronous payment (the provider answered pending) is saved when the payment settles. If that happens after the webhook was sent, data.token is absent and you receive a token.created event instead.

Event	Fires when
`payment.authorized`	Funds were reserved by an `authorization` call (or the auth leg of a `purchase`).
`payment.captured`	A capture succeeded — including the automatic capture inside `purchase`, and the confirmation of an asynchronous APM or voucher payment.
`payment.refused`	The issuer or acquirer declined the payment. Corresponds to a `declined` status on the synchronous API response — see Declined Payments for how to read the refusal.
`payment.refunded`	A refund was processed. Fires on each refund; `data.status` is `refunded` only once the payment is fully refunded.
`payment.canceled`	An authorization was voided before capture.
`payment.chargeback`	A dispute was raised against a settled payment (received from the acquirer’s dispute notification).
`payment.capture_failed`	A capture attempt failed. The payment stays `authorized`.
`payment.refund_failed`	A refund attempt failed. The payment stays `captured`.
`payment.cancel_failed`	A cancel attempt failed. The payment stays `authorized`.

Webhook event names use refused where the synchronous API response status field uses declined, and payment.<status> for terminal states such as expired. Match on the event string, not on substring parsing.

Subscription events

Subscription event payloads use a slightly different envelope — subscription_id is a top-level field and data carries event-specific detail:

{
  "event": "subscription.renewed",
  "created_at": "2026-08-29T12:00:00Z",
  "subscription_id": "sub_abc123",
  "merchant_id": 42,
  "data": {
    "...": "event-specific fields (invoice, period dates, amount, failure reason, ...)"
  }
}

Event	Fires when
`subscription.created`	A subscription was created.
`subscription.trial_ended`	A free trial period ended and billing begins.
`subscription.renewed`	A scheduled renewal was charged successfully.
`subscription.payment_failed`	A renewal charge failed.
`subscription.dunning_started`	The subscription entered `past_due` and the dunning retry sequence began.
`subscription.suspended`	All dunning retries were exhausted; the subscription is inactive until the payment method is updated.
`subscription.reactivated`	A `suspended` subscription was recovered (new payment method or successful retry).
`subscription.paused`	The subscription was manually paused.
`subscription.resumed`	A paused subscription resumed.
`subscription.canceled`	The subscription was permanently canceled.
`subscription.completed`	The subscription reached its fixed number of billing cycles and ended naturally.
`subscription.payment_method_updated`	The stored card on the subscription was replaced.
`subscription.payment_method_removed`	The shopper deleted the saved card that the subscription renews on. The subscription keeps charging that card until you replace its payment method. `data.token` is the token.
`subscription.plan_change_scheduled`	A plan change was queued to apply at the next billing date.
`subscription.plan_changed`	A plan change took effect.

Saved card events

Saved card events tell you when a token is created for an asynchronous payment, and when a token you stored stops being usable. See Token lifecycle for the retention rules.

{
  "event": "token.deleted",
  "environment": "production",
  "created_at": "2026-03-02T14:15:00Z",
  "merchant_id": 42,
  "data": {
    "token": "vt_4xK9mNpQ2rLsT7uV",
    "status": "deleted",
    "reason": "unused",
    "retentionDays": 30
  }
}

Event	Fires when
`token.created`	A card held back until an asynchronous payment settled was saved. `data.token` is the token id (a string, as on `token.deleted`), with `data.payment_id`, `data.payment_code`, `data.expirationDate` and `data.tokenCreationReference`. If the same card was already saved, `data.token` is the existing token.
`token.deleted`	A card was deleted by the shopper or a support agent, replaced by a newer save of the same card, or retired by Therius. `data.reason` is `deleted`, `expired` or `unused`. The token still charges until `token.erased`; `data.retentionDays` is the retention period that applies.
`token.erased`	The card data behind the token was permanently erased. The token can no longer be charged.

Payment link events

A payment link sends its own events in addition to the payment events above. A payment made on a link still sends its usual payment.* events; the payment_link.* events describe what happened to the link itself. Use data.payment_link_id to identify the link, and data.payment_id or data.order_code to match the payment. Payment link events use the same envelope as payment events:

{
  "event": "payment_link.paid",
  "environment": "production",
  "created_at": "2026-10-15T12:00:00Z",
  "data": {
    "payment_link_id": "5b1f0a52-3c0e-4a52-9d57-0c1d7e9f2a10",
    "type": "one-time",
    "title": "Invoice 1042",
    "reference": "INV-1042",
    "merchant_id": 42,
    "status": "used",
    "uses_count": 1,
    "payment_id": "b1f2...",
    "order_code": "INV-1042",
    "payment_status": "captured",
    "amount": 1100,
    "currency": "USD",
    "exponent": 2
  }
}

Event	Fires when
`payment_link.paid`	A payment on the link was approved and counted as a use. `data.status` is `used` once the link can take no more payments (a single-use link, or a reusable link that reached its `maxUses`), otherwise `active`. For a subscription link, `data.subscription_id` is the new subscription.
`payment_link.attempt_failed`	A payment attempt on the link was refused or ended in an error. The link stays `active`, so the payer can try again.
`payment_link.expired`	The link passed its expiry without being paid. Sent once, shortly after the expiry time.
`payment_link.canceled`	The link was canceled, through the API or from the dashboard.

Field	Description
`data.payment_link_id`	The link’s ID.
`data.type`	`one-time` or `subscription`.
`data.title`, `data.reference`	The title and your reference, as set when the link was created. `null` when not set.
`data.merchant_id`, `data.uses_count`	The merchant, and how many successful payments the link has taken so far.
`data.status`	The link’s status after the event: `used`, `expired` or `canceled` (`active` on a reusable link that can still take payments). Not sent with `payment_link.attempt_failed`.
`data.payment_id`, `data.order_code`, `data.payment_status`, `data.amount`, `data.currency`, `data.exponent`	The payment behind the event. Sent with `payment_link.paid` and `payment_link.attempt_failed`. `amount` is in minor units.
`data.subscription_id`	Sent with `payment_link.paid` on a subscription link.
`data.expires_at`	Sent with `payment_link.expired`.
`data.canceled_by`	Sent with `payment_link.canceled`: `api` or `dashboard`.

Link events and the payment events for the same payment are separate deliveries and can arrive in either order. Match them on data.order_code or data.payment_id rather than on arrival order.

Testing events

Use Developers → Webhooks → Send test event to deliver a sample payload for any event type to your endpoint without creating a real payment or subscription. Test deliveries appear in Recent deliveries alongside live ones and can be replayed.

Get Started

Core Concepts

Guides

Webhooks

AI Assistant

E-Commerce Plugins

Therius Webhook Events Catalog and Payloads

Payment events

Subscription events

Saved card events

Payment link events

Testing events

​Payment events

​Subscription events

​Saved card events

​Payment link events

​Testing events

Payment events

Subscription events

Saved card events

Payment link events

Testing events