Skip to main content
WEBHOOK

Authorizations

Authorization
string
header
required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Body

application/json

Payload delivered for every operation lifecycle event — OPERATION_REQUESTED, OPERATION_PROCESSING, OPERATION_ACTION_REQUIRED, OPERATION_COMPLETED, OPERATION_FAILED, OPERATION_REFUNDING and OPERATION_REFUNDED. The seven carry the same shape; inspect the X-Event-Type header — or currentState.status on the payload — to tell which transition fired.

externalId
string | null
required

Your own identifier for the operation, as you sent it on the create request. Free-form: it is not deduplicated, and the same value may appear on more than one operation. null when you sent none, and on a deposit credited from an incoming payment nobody requested.

Required string length: 1 - 255
Example:

"order-2026-0043"

customer
object
required

Reference to the customer that owns the operation.

account
object
required

Reference to a customer account, including the registered owner name.

sourceAmount
object
required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library for arithmetic — never JavaScript Number.

destinationAmount
object
required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library for arithmetic — never JavaScript Number.

intent
Withdrawal · object
required

What the operation was asked to do. Discriminated by type, and the same discriminator travels as the X-Operation-Intent message attribute so a subscription can filter on it.

fees
(Percentage · object | Absolute · object)[]
required

Fee charged on the operation. Discriminated by type.

transactions
(PIX · object | Crypto · object | TED · object | Boleto · object | Internal debit · object | Internal credit · object)[]
required

Underlying rail transactions executed for this operation.

A confirmed rail movement behind the operation. Discriminated by type, which names the rail that moved the money — INTERNAL_DEBIT and INTERNAL_CREDIT are the two legs of a movement that stays inside the platform and touches no external rail.

currentState
object
required

Status the operation is in at the time the event fires.

atTime
string<date-time>
required

When this event occurred. Distinct from the resource's createdAt — events fire on state transitions, so atTime reflects when the transition happened, not when the underlying resource was first created.

Example:

"2026-04-28T14:32:11Z"

quote
object | null

Quote linked to the operation, when applicable. null for same-asset operations or operations without a quote.

tags
object[]

System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags.

Example:

Response

200

Acknowledged. Trace Finance considers any 2xx response a successful delivery.