Integrate Swapped Commerce webhooks and view sample responses we send.
Swapped Commerce Webhook Validation
If you rely on Swapped Commerce webhooks for sensitive flows, like for confirming a product is paid for before shipping it, you should verify that the webhook is coming from the Swapped Commerce API and not some middleman or other source. To validate the webhook is coming from Swapped, you must implement private key signing.
See Webhook Signatures for details on using Webhook API keys to validate a webhook.
Swapped Commerce Webhook Responses
To receive order notifications for Swapped Commerce, you provide a merchant-level webhook on the "Developers" page within the Swapped.com Dashboard. You will receive notifications to the provided URL with a signature in the HTTP request header to validate that the data comes from Swapped.com.
Important: The callback destination is locked at order creation and cannot be changed, even if you later update your merchant-level webhook settings.
Webhook Event Types
[ 1 ] ORDER_CREATED
Triggered when a new order is created but, the currency selection is still pending.
{"eventType":"ORDER_CREATED","orderId":"A5WX6BN6CCPS","orderStatus":"PENDING_CURRENCY_SELECTION","merchantId":"27323275-ea28-4b33-85e4-d25b4d96dbde","orderPurchaseAmount":123,"orderPurchaseCurrency":"USD","testMode":false,"merchantCurrency":"USD","orderPurchaseAmountInMerchantCurrency":"123","externalId":"abc123",// optional, if set"customerId":"cus123"// optional, if set}
[ 2 ] ORDER_COMPLETED
Indicates that the order has been successfully completed with accurate payment confirmation.
[ 3 ] PAYMENT_RECEIVED
Indicates that a cryptocurrency payment has been received. The order status will vary based on the payment accuracy:
[ 3.1 ] Underpaid Orders
When payment is received but the amount is insufficient, the order status remains AWAITING_PAYMENT (displays as "underpaid" on the dashboard):
[ 3.2 ] Overpaid Orders
When payment exceeds the required amount, the order status is still AWAITING_PAYMENT
[ 4 ] SETTLEMENT_CREATED
Triggered when a settlement process begins for currency conversion or transfer.
[ 5 ] SETTLEMENT_SETTLED
Indicates that a conversion, withdrawal, refund, or transfer has been completed.
Field Definitions
eventType: The type of webhook event
orderId: The unique order identifier on Swapped Commerce
orderStatus: Current status of the order
merchantId: Your merchant identifier
orderPurchaseAmount: The original purchase amount
orderPurchaseCurrency: The currency of the purchase amount
orderCrypto: The cryptocurrency received (when applicable)
orderCryptoAmount: The exact cryptocurrency amount received
blockchain: The blockchain used for the transaction
settlementId: Unique identifier for settlement transactions
status: Current status of the settlement
type: Type of settlement (CONVERT, TRANSFER, etc.)
fromAmount/toAmount: Amounts in settlement transactions
fromCurrency/toCurrency: Currencies involved in settlement
fromBlockchain/toBlockchain: Blockchains involved in settlement
fromAmountInMerchantCurrency/toAmountInMerchantCurrency: Amounts in settlement transactions, designated in the merchant's base fiat currency
merchantCurrency: The merchant's base fiat currency
Order State Flow
Swapped Commerce orders follow this typical state flow:
ORDER_CREATED → Order initiated, awaiting currency selection
PAYMENT_RECEIVED → Payment detected (may be underpaid, or overpaid)
ORDER_COMPLETED → Payment confirmed accurate and order finalized
SETTLEMENT_CREATED → Settlement process begins (if conversion needed)
PAYMENT_CONVERSION_SETTLED → Settlement completed
KYC Webhooks
In cases where KYC is utilized, the following webhooks will be sent:
[ 1 ] KYC_INITIALIZED
Indicates that a KYC session has been initialized for a customer:
[ 2 ] KYC_COMPLETE
Indicates that a customer's KYC has been approved
[ 3 ] KYC_FAILED
Indicates that a KYC session has been initialized for a customer:
