Skip to main content
WEBHOOK
OPERATION_COMPLETED
{
  "customerId": "9c7b6a2e-1d3f-4a5b-8c9d-0e1f2a3b4c5d",
  "account": {
    "owner": "Acme Importação Ltda"
  },
  "sourceAmount": {
    "value": "500.00",
    "asset": "BRL",
    "decimals": 2
  },
  "destinationAmount": {
    "value": "500.00",
    "asset": "BRL",
    "decimals": 2
  },
  "intent": {
    "type": "WITHDRAWAL",
    "beneficiary": {
      "entity": {
        "name": "John Doe",
        "taxId": "12345678901",
        "address": {
          "addressLine1": "Rua Augusta, 500",
          "city": "São Paulo",
          "country": "BR",
          "postalCode": "01304-001",
          "addressLine2": null,
          "state": "SP"
        }
      },
      "instruction": {
        "address": {
          "type": "PixKey",
          "rail": "PIX_KEY",
          "key": "12345678901"
        }
      }
    }
  },
  "fees": [
    {
      "type": "PERCENTAGE",
      "amount": {
        "value": "500.00",
        "asset": "BRL",
        "decimals": 2
      },
      "percentage": "0.0050"
    }
  ],
  "transactions": [
    {
      "type": "PIX",
      "amount": {
        "value": "500.00",
        "asset": "BRL",
        "decimals": 2
      },
      "currentState": {
        "createdAt": "2023-11-07T05:31:56Z",
        "reason": "<string>"
      },
      "endToEnd": "<string>"
    }
  ],
  "currentState": {
    "status": "COMPLETED",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "atTime": "2023-11-07T05:31:56Z",
  "tags": [
    {
      "key": "psp",
      "value": "Amazon"
    },
    {
      "key": "compliance-tier",
      "value": "high"
    }
  ]
}

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 operation lifecycle events (OPERATION_REQUESTED, OPERATION_COMPLETED, OPERATION_FAILED). Inspect the X-Event-Type header — or currentState.status on the payload — to tell which transition fired. Intermediate statuses (PROCESSING, ON_HOLD, ACTION_REQUIRED) are not published as webhooks; fetch GET /api/operations/{operationId} if you need them.

​
customerId
string<uuid>
required
Example:

"9c7b6a2e-1d3f-4a5b-8c9d-0e1f2a3b4c5d"

​
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

Operation intent. Discriminated by type.

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

Fee charged on the operation. Discriminated by type.

​
transactions
PIX · object[]
required

Underlying rail transactions executed for this operation.

​
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.

​
quote
object

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:
[
  { "key": "psp", "value": "Amazon" },
  { "key": "compliance-tier", "value": "high" }
]

Response

200

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