Stablecoin Payment Event

When a stablecoin payment order is confirmed, VelaFi sends a signed HTTP POST request to your STABLE_COIN_PAYMENT_WEBHOOK endpoint. This is the only stablecoin payment event VelaFi sends. Orders that are rejected, cancelled, refunded, or flagged for an amount or network mismatch do not trigger a webhook. The payload includes full order details, blockchain transaction data, and the on-chain addresses involved. Your endpoint should verify the signature header and return HTTP 200 with {"callbackStatus": "SUCCESS"} to confirm receipt. VelaFi retries delivery if your endpoint does not respond within the timeout window.

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`

Payload Fields

string

The ID of the webhook endpoint that delivered this event.

string

Always STABLE_COIN_PAYMENT_WEBHOOK for this event type.

string

Unique payment order ID.

string

ID of the user associated with the payment order.

string

ID of the merchant that owns this payment order.

string

ID of the payment link that generated this order.

string

ID of the destination wallet.

string

Human-readable name of the destination wallet.

string

Your merchant-supplied reference number for the order.

string

Stablecoin currency of the payment (e.g., USDT, USDC).

string

Network code (e.g., USDT-POL, USDT-BEP20).

string

Human-readable network name (e.g., Polygon (POS), Binance Smart Chain (BEP20)).

string

Gross amount deposited by the payer.

string

Transaction fee deducted from the deposit.

string

Net amount received after fees (depositAmount - feeAmount).

string

Order status at the time of delivery. Because this webhook is sent when the order is confirmed, the value is normally CONFIRMED.

string

On-chain sender wallet address.

string

On-chain recipient wallet address.

string

Blockchain transaction hash for the on-chain settlement.

string

URL of the payment link associated with this order.

string

Unix timestamp (milliseconds) when the order was created.

string

Unix timestamp (milliseconds) at which the order is cancelled if it is not paid. It is set to 30 minutes after createTime when the order is created, so confirmed orders also have it.

string

Unix timestamp (milliseconds) when processing began.

string

Unix timestamp (milliseconds) when the on-chain transaction was confirmed.

string

Unix timestamp (milliseconds) at which this delivery attempt was signed.

Example Payload

Incoming POST body

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "STABLE_COIN_PAYMENT_WEBHOOK",
  "orderId": "619586512161566720",
  "userId": "9876543",
  "merchantId": "42",
  "linkId": "619570217441521664",
  "walletId": "1",
  "walletName": "Main USDT Wallet",
  "referenceId": "REF-2024-05-03-001",
  "currency": "USDT",
  "network": "USDT-POL",
  "networkName": "Polygon (POS)",
  "depositAmount": "1000",
  "feeAmount": "2.5",
  "receivedAmount": "997.5",
  "status": "CONFIRMED",
  "fromAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "toAddress": "0x9876543210fedcba9876543210fedcba98765432",
  "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "paymentLink": "https://www.velafi.com/velafi-payments?linkId=619570217441521664",
  "createTime": "1714671600000",
  "cancelTime": "1714673400000",
  "processTime": "1714672200000",
  "confirmTime": "1714672800000",
  "timestamp": "1714672801000"
}

Required Response

Return the following JSON body with HTTP status 200:

Your response

{
  "callbackStatus": "SUCCESS"
}

All values are sent as JSON strings. Timestamps are Unix milliseconds, and a timestamp that is not set is sent as the string "null". The txHash uniquely identifies the on-chain settlement — use it to verify finality independently on the blockchain if required by your compliance workflow.

Overview

Account

Configuration

Merchants

Crypto Wallet

Beneficiaries

Quotes

Orders

Webhooks

Stablecoin Payment Event

Request Headers

Payload Fields

Example Payload

Required Response

​Request Headers

​Payload Fields

​Example Payload

​Required Response

Request Headers

Payload Fields

Example Payload

Required Response