Skip to main content
When a fiat/crypto order created through the API enters one of the statuses below, VelaFi sends a signed HTTP POST request to your registered ORDER_WEBHOOK endpoint. Orders not created through the API do not trigger this webhook. The payload contains the full order snapshot — including amounts, pricing, and the updated status code. Your endpoint must verify the signature header and respond with {"callbackStatus": "SUCCESS"} to acknowledge receipt.

​
Request Headers

​
Order Status Codes

Orders that are canceled, rejected in API or risk review, or time out are sent with orderStatus 70. Other statuses, such as 20, 30, 71, and 73, are not sent.

​
Payload Fields

​
string
The ID of the webhook endpoint that delivered this event.
​
string
Always ORDER_WEBHOOK for this event type.
​
string
Unique identifier for the order.
​
string
Your client-supplied order identifier. Omitted if you did not supply one.
​
string
Your VelaFi account (user) ID.
​
string
ID of the merchant this order belongs to.
​
string
ID of the merchant account setting (payment channel) used for the order.
​
string
Direction of the trade: BUY (fiat → crypto) or SELL (crypto → fiat).
​
string
Fiat currency involved in the order, e.g. MXN.
​
string
Fiat amount for the order.
​
string
Fiat amount actually paid or received.
​
string
Fiat fee charged for the order.
​
string
Cryptocurrency involved in the order, e.g. USDT.
​
string
Crypto amount for the order.
​
string
Exchange rate at which the order was executed (fiat per unit of crypto).
​
string
Current order status code. See the status table above.
​
string
Machine-readable failure code. Present only for canceled (70) or refunded (72) orders that have a recorded failure code; omitted otherwise.
​
string
Human-readable failure description. Present only when failCode is present and a description is recorded.
​
string
Unix timestamp (milliseconds) when the order was created.
​
string
Unix timestamp (milliseconds) when the order was last updated.
​
string
Unix timestamp (milliseconds) at which this delivery attempt was signed.
For backward compatibility, the payload also contains fiatCurrency, orderAmount, arriveOrderAmount, mcSettingsId, cryptoCurrency, and quantity, which repeat fiat, fiatAmount, arriveFiatAmount, settingsId, crypto, and cryptoAmount. Some orders include additional fields, such as bankOrderId. Ignore any fields you do not use.

​
Example Payload

Incoming POST body

​
Required Response

Return the following JSON body with HTTP status 200 to acknowledge receipt:
Your response
VelaFi retries delivery if your endpoint returns a non-2xx status, does not respond in time, or returns any other body. The same event can arrive more than once, so deduplicate on orderId together with orderStatus. See Delivery and Retries.