Global Payment Event

When a fiat-to-fiat global payment order created through the API enters one of the statuses below, VelaFi sends a signed HTTP POST request to your GLOBAL_PAYMENT_WEBHOOK endpoint. The payload describes both sides of the cross-border payment — the on-ramp (source country/currency) and the off-ramp (destination country/currency) — along with the current order status. Verify the signature header and respond with {"callbackStatus": "SUCCESS"} to acknowledge receipt.

Request Headers

Header	Description
`signature`	RSA-SHA256 signature of the raw request body, hex-encoded. Use your webhook’s `publicKey` to verify. See Webhook Setup.
`Content-Type`	`application/json`

Order Status Codes

Code	Meaning
`10`	Reviewing — order is under compliance review
`31`	Documents Pending — required documents must be provided
`41`	Payin Pending — awaiting fiat deposit from sender
`51`	Payout Pending — crypto received, fiat payout in progress
`60`	Released — order complete
`71`	Payin Canceled — on-ramp leg was canceled
`72`	Payout Canceled — off-ramp leg was canceled

Other global payment statuses are not sent.

Payload Fields

string

The ID of the webhook endpoint that delivered this event.

string

Always GLOBAL_PAYMENT_WEBHOOK for this event type.

string

Unique identifier for the global payment order.

string

Your client-supplied order identifier. Omitted if you did not supply one.

string

Your VelaFi account (user) ID.

string

Name of the source country (e.g., Mexico).

string

ID of the on-ramp merchant processing the source-side payment. Omitted when not set.

string

Fiat currency collected from the sender (e.g., MXN).

string

Amount collected from the sender in the source currency.

string

Fee charged on the on-ramp side. Omitted when not set.

string

Name of the destination country (e.g., Hong Kong).

string

ID of the off-ramp merchant processing the destination-side payment. Omitted when not set.

string

Fiat currency delivered to the recipient (e.g., USD).

string

Amount delivered to the recipient in the destination currency.

string

Fee charged on the off-ramp side. Omitted when not set.

string

Effective exchange rate between the on-ramp and off-ramp currencies.

string

Current order status code. See the status table above.

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.

Example Payload

Incoming POST body

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "GLOBAL_PAYMENT_WEBHOOK",
  "orderId": "473130522693193728",
  "clientId": "W658784738723",
  "userId": "455472",
  "onRampCountry": "Mexico",
  "onRampMerchantId": "3",
  "onRampFiat": "MXN",
  "onRampFiatAmount": "100",
  "onRampFiatFee": "0",
  "offRampCountry": "Hong Kong",
  "offRampMerchantId": "4",
  "offRampFiat": "USD",
  "offRampFiatAmount": "18",
  "offRampFiatFee": "2",
  "orderPrice": "20",
  "orderStatus": "41",
  "createTime": "1735279907000",
  "updateTime": "1735280582000",
  "timestamp": "1735280582345"
}

Required Response

Return the following JSON body with HTTP status 200 to acknowledge receipt:

Your response

{
  "callbackStatus": "SUCCESS"
}

The webhook fires only for the statuses listed above. A status can be skipped if the order has already moved on when a delivery is attempted. The same event can arrive more than once, so deduplicate on orderId together with orderStatus. See Delivery and Retries.

⌘I

Overview

Account

Configuration

Merchants

Crypto Wallet

Beneficiaries

Quotes

Orders

Webhooks

Global Payment Event

Request Headers

Order Status Codes

Payload Fields

Example Payload

Required Response

​Request Headers

​Order Status Codes

​Payload Fields

​Example Payload

​Required Response

Request Headers

Order Status Codes

Payload Fields

Example Payload

Required Response