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.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, and carries captured_amount and the closing capture's identifiers.
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.underpaid	The payer sent less than amount and the provider is holding the funds until you accept or decline them. The payment stays processing.
payment.overpaid	The payer sent more than amount and the provider is holding the funds until you accept or decline them. The payment stays processing.
payment.returned	The provider sent a held under- or overpayment back to the payer after you declined it. The payment ends returned.

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.
parent_transaction_id	string	yes	Only on the payment.succeeded of an accepted under- or overpayment: the held payment that transaction_id replaced. Absent otherwise.
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.
processing_profile	string	yes	The processing profile code the payment was addressed to; absent at account scope.
provider_reference	string	yes	The reference Upprove sent the provider for this attempt.
status	string	no	Transaction status (lowercase), e.g. completed, failed.
amount	number	no	Decimal amount. On a card payment, the authorized amount.
processing_amount	number	yes	What the provider actually processed, when it reports an amount in a different currency from currency (e.g. the cryptocurrency of a crypto pay-in). Absent otherwise.
processing_currency	string	yes	The currency of processing_amount. Absent alongside it.
captured_amount	number	yes	Cumulative settled captured total on the authorization. Present on payment.partially_captured and on the payment.succeeded a capture closes; absent otherwise. May be less than amount after a partial final capture.
capture_transaction_id	string	yes	The capture that closed the payment. Only on a payment.succeeded closed by a capture.
capture_provider_transaction_id	string	yes	The provider's reference for that closing capture.
amount_mismatch	boolean	yes	true on every event for an order whose payer sent a different amount from the one requested - see Under- and overpayments. Never false; absent otherwise.
received_amount	number	yes	What the payer actually sent, in currency. Present whenever amount_mismatch is.
returned_amount	number	yes	What went back to the payer. Only on payment.returned.
return_transaction_id	string	yes	The return transaction that carried the funds back. Only on payment.returned.
currency	string	no	ISO 4217 currency code.
payment_method	string	yes	Payment method code used, when known.
provider	string	yes	The provider that ran the attempt (lowercase), e.g. stripe, when known.
payment_instrument	object	yes	The instrument the transaction ran on, when known, e.g. the card brand (lowercase) and last four digits on a card payment.
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.
stored_credential_initiator	string	yes	Who initiated a charge on a stored card, as declared on the create: customer or merchant. Absent means customer-initiated.
stored_credential_reason	string	yes	The agreement a merchant-initiated charge ran under: recurring, unscheduled, or installment.
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",
    "provider": "stripe",
    "payment_instrument": {
      "id": "pi_8a7b6c5d",
      "type": "card",
      "country_code": "GB",
      "holder_name": "Jane Doe",
      "card_brand": "visa",
      "last4_digits": "4242",
      "bin": "42424242",
      "card_funding": "credit",
      "card_product": "platinum",
      "issuer_name": "Commonwealth Bank"
    },
    "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": "stripe",
    "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": "stripe",
    "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.

Example - payment.succeeded after a capture

The event is anchored on the authorization (transaction_id, amount) and names what settled: captured_amount and the closing capture. Here a final £30 capture closed the £42 hold above, so amount stays 42.00:

{
  "id": "evt_4d5e6f708192a3b4",
  "type": "payment.succeeded",
  "created": 1719063600,
  "data": {
    "transaction_id": "txn_9f8e7d6c",
    "order_id": "ord_5b4a3c2d",
    "session_id": null,
    "merchant_reference": "order-1001",
    "status": "completed",
    "amount": 42.00,
    "captured_amount": 30.00,
    "capture_transaction_id": "txn_2c3d4e5f",
    "capture_provider_transaction_id": "ch_3PqRsT2eZvKYlo2C1aBcD3eF",
    "currency": "GBP",
    "payment_method": "card",
    "provider": "stripe",
    "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-22T12:00:00Z"
  }
}

A void behind settled partial captures closes the payment the same way, as payment.succeeded for the captured total. payment.canceled fires only when a void releases a hold with nothing captured.

Example - payment.underpaid

A €100 crypto payment where the payer's coins were worth €95. amount stays the requested charge and received_amount is what arrived; the provider holds the funds until you accept or decline them:

{
  "id": "evt_5e6f708192a3b4c5",
  "type": "payment.underpaid",
  "created": 1719064800,
  "data": {
    "transaction_id": "txn_9f8e7d6c",
    "order_id": "ord_5b4a3c2d",
    "session_id": "cs_7e6d5c4b",
    "merchant_reference": "order-1001",
    "status": "processing",
    "amount": 100.00,
    "amount_mismatch": true,
    "received_amount": 95.00,
    "currency": "EUR",
    "payment_method": "crypto",
    "provider": "crypto_provider",
    "provider_transaction_id": "prv_8821734",
    "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-22T12:20:00Z"
  }
}

One event fires per amount the provider reports, so a payer who tops up to another amount that still differs triggers a new payment.underpaid or payment.overpaid.

Example - payment.succeeded after an accepted underpayment

Accepting settles the received amount on a new transaction. transaction_id and amount describe that new payment; parent_transaction_id names the held one, which ends canceled with no payment.canceled of its own:

{
  "id": "evt_6f708192a3b4c5d6",
  "type": "payment.succeeded",
  "created": 1719065400,
  "data": {
    "transaction_id": "txn_4b5c6d7e",
    "parent_transaction_id": "txn_9f8e7d6c",
    "order_id": "ord_5b4a3c2d",
    "session_id": "cs_7e6d5c4b",
    "merchant_reference": "order-1001",
    "status": "completed",
    "amount": 95.00,
    "amount_mismatch": true,
    "received_amount": 95.00,
    "currency": "EUR",
    "processing_amount": 0.00142,
    "processing_currency": "BTC",
    "payment_method": "crypto",
    "provider": "crypto_provider",
    "provider_transaction_id": "prv_8821734",
    "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-22T12:30:00Z"
  }
}

Example - payment.returned

Declining sends the funds back. The event is anchored on the held payment (transaction_id, amount), now returned, and names the return transaction that carried the funds back:

{
  "id": "evt_708192a3b4c5d6e7",
  "type": "payment.returned",
  "created": 1719066000,
  "data": {
    "transaction_id": "txn_9f8e7d6c",
    "order_id": "ord_5b4a3c2d",
    "session_id": "cs_7e6d5c4b",
    "merchant_reference": "order-1001",
    "status": "returned",
    "amount": 100.00,
    "amount_mismatch": true,
    "received_amount": 95.00,
    "returned_amount": 95.00,
    "return_transaction_id": "txn_6e5f4a3b",
    "currency": "EUR",
    "processing_amount": 0.00142,
    "processing_currency": "BTC",
    "payment_method": "crypto",
    "provider": "crypto_provider",
    "provider_transaction_id": "prv_8821734",
    "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": false,
    "customer_id": "cus_8a7b6c5d",
    "metadata": {
      "cart_id": "C-1001"
    },
    "event_time": "2024-06-22T13:00:00Z"
  }
}

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. On a session created with capture_method: manual this fires at authorization, before any capture - see Manual capture on hosted checkout. It also fires when a declined under- or overpayment is returned to the payer, just before payment.returned - nothing was paid in that case.
checkout.session.expired	The session expired before completion.
checkout.session.canceled	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.
processing_profile	string	yes	The processing profile code the session was addressed to; absent at account scope.
status	string	no	Session status (lowercase), e.g. completed, expired, canceled, failed.
amount	number	no	Decimal amount.
currency	string	no	ISO 4217 currency code.
capture_method	string	yes	automatic or manual, present when the session was created with one. On manual, a completed session is a hold you still have to capture.
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, failed or canceled. parent_transaction_id is not set on refund events - 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.
refund.canceled	The refund was canceled before it completed - the provider canceled it, or its approval request was declined. No money moved.

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": "stripe",
    "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": "stripe",
    "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": "stripe",
    "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"
  }
}

Approval request events

These are sent only when approval workflows are enabled on your account (configured in the portal). A gated payout, refund or transfer is not sent to the provider until it is approved: its transaction and order stay pending until then. If the request is approved, it continues through its normal payout.*, refund.* or transfer.* events. If it is declined, the transaction is canceled and its own payout.canceled, refund.canceled or transfer.canceled follows. They share the approval request payload below.

Event type	When it fires
approval_request.pending	The transaction matched an approval workflow and is waiting for approval. Carries every step of the workflow in steps, so you know up front what it takes.
approval_request.new_approval	An approver recorded an approval. Fires once per approval, so a step that needs two approvals fires it twice.
approval_request.approved	The last required approval was recorded and the transaction is submitted to the provider. It follows the approval_request.new_approval for that last approval.
approval_request.declined	An approver declined the request, or the person who initiated it withdrew it.

Approval request payload

Field	Type	Nullable	Description
approval_request_id	string	no	The approval request.
status	string	no	Request status (lowercase): pending_approval, approved or declined.
subject_type	string	no	What the request gates. Always money_out today.
subject_id	string	no	The gated entity. For money_out, the transaction id.
transaction_id	string	yes	The gated payout, refund or transfer transaction. Set for money_out.
operation_type	string	yes	The kind of money-out (lowercase): payout, refund or transfer.
amount	number	no	Decimal amount of the gated transaction.
currency	string	no	ISO 4217 currency code.
merchant_reference	string	yes	Your reference for the gated transaction.
workflow_name	string	no	The approval workflow that matched.
current_step	integer	no	The step the request is on, counted from 1.
total_steps	integer	no	How many steps the workflow has.
step_name	string	yes	The step this event concerns.
approvals_received	integer	yes	Approvals recorded on that step so far. Absent on approval_request.declined.
required_approvals	integer	yes	Approvals that step needs. Absent on approval_request.declined.
steps	array	no	Every step of the workflow, in order, as { "name", "required_approvals" }.
actor	object	yes	Who acted: id, type (user, api_key or system), name and email. Absent on approval_request.pending.
note	string	yes	The note the actor left, if any.
decline_reason	string	yes	Why the request was declined. Only on approval_request.declined.
event_time	string (date-time)	no	When the event occurred (ISO 8601).

Example - approval_request.new_approval

The first of two approvals on the first step of a two-step workflow:

{
  "id": "evt_708192030415263a",
  "type": "approval_request.new_approval",
  "created": 1719070800,
  "data": {
    "approval_request_id": "apr_3e4f5a6b",
    "status": "pending_approval",
    "subject_type": "money_out",
    "subject_id": "txn_1c2b3a4d",
    "transaction_id": "txn_1c2b3a4d",
    "operation_type": "payout",
    "amount": 5000.00,
    "currency": "GBP",
    "merchant_reference": "payout-1002",
    "workflow_name": "Large payouts",
    "current_step": 1,
    "total_steps": 2,
    "step_name": "Finance review",
    "approvals_received": 1,
    "required_approvals": 2,
    "steps": [
      { "name": "Finance review", "required_approvals": 2 },
      { "name": "Director sign-off", "required_approvals": 1 }
    ],
    "actor": {
      "id": "usr_9a8b7c6d",
      "type": "user",
      "name": "Alex Smith",
      "email": "alex@example.com"
    },
    "note": "Matches the supplier invoice.",
    "event_time": "2024-06-22T14: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. If you accept crypto, also handle the under- and overpayment events: a returned payment completes its session too.

See Retries for delivery guarantees and idempotency.