Webhook event types

Event types are named <resource>.<action>. This page documents the events Orchestr currently emits and the data payload each one carries. (Additional event families are planned; only the events below are emitted today.)

All data fields are snake_case. status values are lowercase. Fields marked nullable may be absent or null.

Payment events

These events report the lifecycle of a payment transaction. They all share the payment payload below.

Event type	When it fires
payment.created	A payment transaction has been created.
payment.processing	The payment is being processed by the provider.
payment.succeeded	The payment completed successfully. On a manual-capture payment this is also the settlement event — it fires once per payment, when the capture that closes the authorization settles.
payment.failed	The payment failed.
payment.canceled	The payment was canceled.
payment.requires_action	The payment needs customer action (e.g. a 3-DS challenge).
payment.authorized	Manual capture only: the card was authorized and funds are held, but nothing has moved.
payment.partially_captured	A capture settled but left the authorization open (a non-final partial capture). The closing capture emits payment.succeeded instead.
payment.capture_failed	A capture did not settle — refused inline, a transport failure, or a pending capture the provider later reported failed. No money moved and the authorization stands.

Payment payload

Fields are grouped logically: identifiers, then status, money, the provider/failure details, and finally customer, metadata, and timing.

Field	Type	Nullable	Description
transaction_id	string	no	The transaction this event concerns.
order_id	string	no	The owning order.
session_id	string	yes	The checkout session, if the payment originated from one.
merchant_reference	string	no	Your reference for the order.
status	string	no	Transaction status (lowercase), e.g. completed, failed.
amount	number	no	Decimal amount.
captured_amount	number	yes	Cumulative settled captured total on the authorization. Present on capture events only; null on a failed capture. May be less than amount after a partial capture.
currency	string	no	ISO 4217 currency code.
payment_method	string	yes	Payment method used, when known.
card	object	yes	Present on card payments: {card_token, brand, last4, saved}. saved is true only when the cardholder consented to storing the card — only then may card_token be charged again.
provider_transaction_id	string	yes	The provider's transaction identifier.
provider_error_code	string	yes	The provider's own error code, verbatim. null on success and when the provider never answered.
provider_error_reason	string	yes	The provider's own error message, verbatim. Do not parse it.
network_error_code	string	yes	Raw card-network (scheme) error code, only when the provider relays one.
network_error_reason	string	yes	Raw card-network (scheme) error message, only when the provider relays one.
decline_code	string	yes	Canonical decline code; null on success.
decline_category	string	yes	The kind of failure (funds, instrument, authentication, …); null on success.
decline_source	string	yes	Who originated the decline (issuer, acquirer, network, …); null on success.
retry_advice	string	yes	Network retry verdict for this attempt; null on success or when no advice was given.
retryable	boolean	yes	Whether the customer can retry on the same session; null on success.
customer_id	string	yes	The customer, when known.
metadata	object (string→string)	yes	Metadata you attached to the order.
event_time	string (date-time)	no	When the event occurred (ISO 8601).

Example — payment.succeeded

{
  "id": "evt_1a2b3c4d5e6f7081",
  "type": "payment.succeeded",
  "created": 1719056400,
  "data": {
    "transaction_id": "txn_9f8e7d6c",
    "order_id": "ord_5b4a3c2d",
    "session_id": "cs_7e6d5c4b",
    "merchant_reference": "order-1001",
    "status": "completed",
    "amount": 42.00,
    "currency": "GBP",
    "payment_method": "card",
    "card": {
      "card_token": "tok_1PqRsT2eZvKYlo2C",
      "brand": "visa",
      "last4": "4242",
      "saved": true
    },
    "provider_transaction_id": "pi_3PqRsT2eZvKYlo2C1aBcD3eF",
    "provider_error_code": null,
    "provider_error_reason": null,
    "network_error_code": null,
    "network_error_reason": null,
    "decline_code": null,
    "decline_category": null,
    "decline_source": null,
    "retry_advice": null,
    "retryable": null,
    "customer_id": "cus_8a7b6c5d",
    "metadata": {"cart_id": "C-1001"},
    "event_time": "2024-06-22T10:00:00Z"
  }
}

Example — payment.failed

{
  "id": "evt_2b3c4d5e6f708192",
  "type": "payment.failed",
  "created": 1719056460,
  "data": {
    "transaction_id": "txn_9f8e7d6c",
    "order_id": "ord_5b4a3c2d",
    "session_id": "cs_7e6d5c4b",
    "merchant_reference": "order-1001",
    "status": "failed",
    "amount": 42.00,
    "currency": "GBP",
    "payment_method": "card",
    "provider_transaction_id": "pi_3PqRsT2eZvKYlo2C1aBcD3eF",
    "provider_error_code": "card_declined",
    "provider_error_reason": "Your card was declined.",
    "network_error_code": "51",
    "network_error_reason": "Insufficient funds",
    "decline_code": "insufficient_funds",
    "decline_category": "funds",
    "decline_source": "issuer",
    "retry_advice": "do_not_retry",
    "retryable": true,
    "customer_id": "cus_8a7b6c5d",
    "metadata": {"cart_id": "C-1001"},
    "event_time": "2024-06-22T10:01:00Z"
  }
}

Example — payment.partially_captured

A £30 capture against a £42 authorization, sent with final: false so the remaining £12 stays capturable. captured_amount is the cumulative settled total, not the amount of this capture:

{
  "id": "evt_3c4d5e6f708192a3",
  "type": "payment.partially_captured",
  "created": 1719060000,
  "data": {
    "transaction_id": "txn_2c3d4e5f",
    "order_id": "ord_5b4a3c2d",
    "session_id": null,
    "merchant_reference": "order-1001",
    "status": "completed",
    "amount": 42.00,
    "captured_amount": 30.00,
    "currency": "GBP",
    "payment_method": "card",
    "provider_transaction_id": "pi_3PqRsT2eZvKYlo2C1aBcD3eF",
    "provider_error_code": null,
    "provider_error_reason": null,
    "network_error_code": null,
    "network_error_reason": null,
    "decline_code": null,
    "decline_category": null,
    "decline_source": null,
    "retryable": null,
    "customer_id": "cus_8a7b6c5d",
    "metadata": {"cart_id": "C-1001"},
    "event_time": "2024-06-22T11:00:00Z"
  }
}

The capture that finally closes the authorization emits payment.succeeded, not another payment.partially_captured. See Manual capture.

Checkout session events

These report the outcome of a hosted checkout session. They share the checkout session payload below.

Event type	When it fires
checkout.session.completed	The customer completed payment on the session.
checkout.session.expired	The session expired before completion.
checkout.session.cancelled	The session was cancelled.
checkout.session.failed	Payment on the session failed terminally.

Checkout session payload

Field	Type	Nullable	Description
session_id	string	no	The checkout session.
order_id	string	no	The associated order.
transaction_id	string	yes	The resulting transaction, when one exists.
merchant_reference	string	no	Your reference for the order.
status	string	no	Session status (lowercase), e.g. completed, expired, cancelled, failed.
amount	number	no	Decimal amount.
currency	string	no	ISO 4217 currency code.
customer_id	string	yes	The customer, when known.
metadata	object (string→string)	yes	Metadata you attached to the session.
event_time	string (date-time)	no	When the event occurred (ISO 8601).

Example — checkout.session.completed

{
  "id": "evt_3c4d5e6f70819203",
  "type": "checkout.session.completed",
  "created": 1719056405,
  "data": {
    "session_id": "cs_7e6d5c4b",
    "order_id": "ord_5b4a3c2d",
    "transaction_id": "txn_9f8e7d6c",
    "merchant_reference": "order-1001",
    "status": "completed",
    "amount": 42.00,
    "currency": "GBP",
    "customer_id": "cus_8a7b6c5d",
    "metadata": {"cart_id": "C-1001"},
    "event_time": "2024-06-22T10:00:05Z"
  }
}

Refund events

These report the lifecycle of a refund. They reuse the payment payload above, with some fields always null on the refund path: session_id (refunds have no checkout session), metadata, and the decline attributes decline_category, decline_source, retry_advice, and retryable. Note decline_code is not always null — a failed refund can carry a canonical decline_code. amount and currency reflect the refund, which may be partial; status is a transaction status that moves from pending to completed or failed. parent_transaction_id is not part of the webhook payload — use provider_transaction_id and your merchant_reference to reconcile.

Event type	When it fires
refund.created	A refund has been created and is pending.
refund.succeeded	The refund completed at the provider.
refund.failed	The refund failed.

Example — refund.succeeded

{
  "id": "evt_4d5e6f7081920304",
  "type": "refund.succeeded",
  "created": 1719060000,
  "data": {
    "transaction_id": "txn_2d3e4f5a",
    "order_id": "ord_5b4a3c2d",
    "session_id": null,
    "merchant_reference": "refund-1001",
    "status": "completed",
    "amount": 42.00,
    "currency": "GBP",
    "payment_method": "card",
    "provider_transaction_id": "re_3PqRsT2eZvKYlo2C1aBcD3eF",
    "provider_error_code": null,
    "provider_error_reason": null,
    "network_error_code": null,
    "network_error_reason": null,
    "decline_code": null,
    "decline_category": null,
    "decline_source": null,
    "retry_advice": null,
    "retryable": null,
    "customer_id": "cus_8a7b6c5d",
    "metadata": null,
    "event_time": "2024-06-22T11:00:00Z"
  }
}

Payout events

These report the lifecycle of a payout. They reuse the payment payload above, built from the payout transaction. amount and currency reflect the payout; status is a transaction status that moves from pending through to completed or failed. The session/decline attributes — session_id, payment_method, decline_code, decline_category, decline_source, retry_advice, retryable — and metadata are null on the payout path. Use provider_transaction_id and your merchant_reference to reconcile.

Event type	When it fires
payout.created	A payout has been created and is pending.
payout.processing	The payout is being processed by the provider.
payout.paid	The payout completed at the provider.
payout.failed	The payout failed.
payout.canceled	The payout was canceled.

Example — payout.paid

{
  "id": "evt_5e6f708192030415",
  "type": "payout.paid",
  "created": 1719063600,
  "data": {
    "transaction_id": "txn_1c2b3a4d",
    "order_id": "pou_5b4a3c2d",
    "session_id": null,
    "merchant_reference": "payout-1001",
    "status": "completed",
    "amount": 10.00,
    "currency": "GBP",
    "payment_method": null,
    "provider_transaction_id": "po_3PqRsT2eZvKYlo2C1aBcD3eF",
    "provider_error_code": null,
    "provider_error_reason": null,
    "network_error_code": null,
    "network_error_reason": null,
    "decline_code": null,
    "decline_category": null,
    "decline_source": null,
    "retry_advice": null,
    "retryable": null,
    "customer_id": "cus_8a7b6c5d",
    "metadata": null,
    "event_time": "2024-06-22T12:00:00Z"
  }
}

Transfer events

These report the lifecycle of a transfer. Like payout events, they reuse the payment payload built from the transfer transaction, with the same session/decline fields and metadata always null. amount and currency reflect the transfer; status moves from pending to completed or failed.

Event type	When it fires
transfer.created	A transfer has been created and is pending.
transfer.processing	The transfer is being processed by the provider.
transfer.paid	The transfer completed at the provider.
transfer.failed	The transfer failed.
transfer.canceled	The transfer was canceled.

Example — transfer.paid

{
  "id": "evt_6f70819203041526",
  "type": "transfer.paid",
  "created": 1719067200,
  "data": {
    "transaction_id": "txn_1c2b3a4d",
    "order_id": "trf_5b4a3c2d",
    "session_id": null,
    "merchant_reference": "transfer-1001",
    "status": "completed",
    "amount": 250.00,
    "currency": "GBP",
    "payment_method": null,
    "provider_transaction_id": "tr_3PqRsT2eZvKYlo2C1aBcD3eF",
    "provider_error_code": null,
    "provider_error_reason": null,
    "network_error_code": null,
    "network_error_reason": null,
    "decline_code": null,
    "decline_category": null,
    "decline_source": null,
    "retry_advice": null,
    "retryable": null,
    "customer_id": null,
    "metadata": null,
    "event_time": "2024-06-22T13:00:00Z"
  }
}

Choosing what to listen to

A payment.succeeded and a checkout.session.completed often describe the same successful purchase from different angles. For most hosted-checkout integrations, checkout.session.completed is the event to fulfil orders on; use the payment events for finer-grained transaction tracking and for direct (non-session) payments.

See Retries for delivery guarantees and idempotency.