💬Order Webhooks

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. To get a private key (secretKey below) to decode the signature, go to the Developers Page of the Swapped Commerce merchant dashboard. This will only display once when you generate the API Key, so keep it somewhere secure. Use this private key and the payload to generate a signature on your end. We include in our requests an x-swapped-signature in the header of the Swapped Commerce webhook, which you then use to confirm the signature you generate matches the x-swapped-signature header we send. To get the signature: Compute an HMAC with a SHA-256 hash function. Use your secret API key as the key and use the request body as the message. Compare this to the signature sent in the request header. Example with NodeJS:

import crypto from 'crypto';

const secretKey = 'sk_test_key'; // Replace with your secret key
const requestBody = '{ "order_id": "9fcc45a5-4def-4953-9bd8-9ff75d9aaa9c"}'
const signature =
  crypto
    .createHmac('sha256', secretKey)
    .update(requestBody)
    .digest('base64');

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

ORDER_CREATED

Triggered when a new order is created but, the currency selection is still pending.

{
  "event_type": "ORDER_CREATED",
  "order_id": "A5WX6BN6CCPS",
  "order_status": "PENDING_CURRENCY_SELECTION",
  "merchant_id": "27323275-ea28-4b33-85e4-d25b4d96dbde",
  "order_purchase_amount": 123,
  "order_purchase_currency": "USD"
}

PAYMENT_RECEIVED

Indicates that a cryptocurrency payment has been received. The order status will vary based on the payment accuracy:

Underpaid Orders

When payment is received but the amount is insufficient, the order status remains AWAITING_PAYMENT (displays as "underpaid" on the dashboard):

{
  "event_type": "PAYMENT_RECEIVED",
  "order_id": "MFT82BKE9HGW",
  "order_status": "PAYMENT_CONFIRMED_UNDERPAID",
  "merchant_id": "71001fb5-b052-40bf-8a7a-b2e7477dee3a",
  "order_purchase_amount": 100,
  "order_purchase_currency": "USD",
  "order_crypto": "ETH",
  "order_crypto_amount": 0.000248877562194502,
  "network": "Ethereum"
}

Overpaid Orders

When payment exceeds the required amount, the order status is still AWAITING_PAYMENT

{
  "event_type": "PAYMENT_RECEIVED",
  "order_id": "46WF9GMESZ1I",
  "order_status": "PAYMENT_CONFIRMED_OVERPAID",
  "merchant_id": "71001fb5-b052-40bf-8a7a-b2e7477dee3a",
  "order_purchase_amount": 2,
  "order_purchase_currency": "USD",
  "order_crypto": "ETH",
  "order_crypto_amount": 0.001243505791006468,
  "network": "Ethereum"
}

ORDER_COMPLETED

Indicates that the order has been successfully completed with accurate payment confirmation.

{
  "event_type": "ORDER_COMPLETED",
  "order_id": "VQYXLRD4VWDC",
  "order_status": "PAYMENT_CONFIRMED_ACCURATE",
  "merchant_id": "71001fb5-b052-40bf-8a7a-b2e7477dee3a",
  "order_purchase_amount": 1,
  "order_purchase_currency": "EUR",
  "order_crypto": "SOL",
  "order_crypto_amount": 0.006
}

SETTLEMENT_CREATED

Triggered when a settlement process begins for currency conversion or transfer.

{
  "event_type": "SETTLEMENT_CREATED",
  "settlement_id": "70dc4b8e-06e0-4379-bbd4-865cfce229e3",
  "status": "PENDING",
  "type": "CONVERT",
  "merchant_id": "27323275-ea28-4b33-85e4-d25b4d96dbde",
  "from_amount": 0.0028,
  "from_currency": "ETH",
  "from_network": "Ethereum",
  "to_currency": "USD"
}

PAYMENT_CONVERSION_SETTLED

Indicates that a payment conversion or transfer has been completed.

{
  "event_type": "PAYMENT_CONVERSION_SETTLED",
  "settlement_id": "7fb68144-3b89-4265-a373-df306281da3f",
  "status": "SETTLED",
  "type": "TRANSFER",
  "merchant_id": "27323275-ea28-4b33-85e4-d25b4d96dbde",
  "order_id": "D126C8UGVJ8P",
  "from_amount": 0.015,
  "from_currency": "LTC",
  "from_network": "Litecoin",
  "to_amount": 0.01489,
  "to_currency": "LTC",
  "to_network": "Litecoin"
}

Field Definitions

  • event_type: The type of webhook event

  • order_id: The unique order identifier on Swapped Commerce

  • order_status: Current status of the order

  • merchant_id: Your merchant identifier

  • order_purchase_amount: The original purchase amount

  • order_purchase_currency: The currency of the purchase amount

  • order_crypto: The cryptocurrency received (when applicable)

  • order_crypto_amount: The exact cryptocurrency amount received

  • network: The blockchain network used for the transaction

  • settlement_id: Unique identifier for settlement transactions

  • status: Current status of the settlement

  • type: Type of settlement (CONVERT, TRANSFER, etc.)

  • from_amount/to_amount: Amounts in settlement transactions

  • from_currency/to_currency: Currencies involved in settlement

  • from_network/to_network: Networks involved in settlement

Order State Flow

Swapped Commerce orders follow this typical state flow:

  1. ORDER_CREATED → Order initiated, awaiting currency selection

  2. PAYMENT_RECEIVED → Payment detected (may be underpaid, or overpaid)

  3. ORDER_COMPLETED → Payment confirmed accurate and order finalized

  4. SETTLEMENT_CREATED → Settlement process begins (if conversion needed)

  5. PAYMENT_CONVERSION_SETTLED → Settlement completed

PreviousAPI KeyNextEndpoints

Last updated