Skip to main content
Event type: payout.update The event type is always payout.update regardless of the transition — read data.state (and data.previousState) to know what happened. See Webhooks overview for delivery, headers, and signature verification.

​
data fields

​
payoutId
string
The payout identifier.
​
companyId
string
Your company identifier.
​
externalId
string
Your external reference, if one was provided.
​
onBehalfOf
string
The end user/entity the payout was made for.
​
previousState
string | null
The state before this transition. null on the first event.
​
state
string
The current payout state. See the table below.
​
amount
number
The payout amount, in minor units (e.g. cents).
​
currency
string
The destination currency.
​
destinationType
string
One of wallet, bank, or qr_code.
​
errorReason
string
Present only when the payout failed.
​
txHash
string
On-chain transaction hash. Present for wallet and bank destinations.
​
extraData
object
Bank-rail metadata. Present only for destinationType = bank.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-update timestamp.

​
Payout states (data.state)

StateMeaning
createdPayout created
in_reviewIn review (pre-partner)
awaiting_fundsAwaiting funds
funds_receivedFunds received
payment_submittedSubmitted / in progress
payment_processedCompleted successfully
undeliverableUndeliverable
returnedReturned
refundedRefunded
canceledCanceled
errorError / failed
{
  "type": "payout.update",
  "timestamp": "2026-06-23T12:00:00.000Z",
  "data": {
    "payoutId": "3ddd0e5b-6276-4b48-b756-c1fcc9a2efd1",
    "companyId": "cmp_123",
    "externalId": "ext-001",
    "onBehalfOf": "user-123",
    "previousState": "payment_submitted",
    "state": "payment_processed",
    "amount": 100000,
    "currency": "cop",
    "destinationType": "bank",
    "txHash": "0xabc123",
    "extraData": {
      "finalAmount": "99950",
      "finalAmountCurrency": "cop",
      "uetr": "97ed4827-7b6f-4b1a-9b0e-2a1c3d4e5f60",
      "trackingNumber": "TRK-0001"
    },
    "createdAt": "2026-06-23T11:00:00.000Z",
    "updatedAt": "2026-06-23T12:00:00.000Z"
  }
}