💬Order Notifications

To receive order notifications. Configure a callback URL either per-order through responseUrl or at the merchant level via the Swapped Dashboard.

Callback URL Priority

1. responseUrl in the iframe URL (if provided)

2. Merchant-level webhook in Dashboard (if configured)

3. No callback (if neither is set)

Important: The callback destination is locked at order creation and cannot be changed afterwards.

Callbacks may be resent due to network errors. Always verify an order hasn't already been credited before processing. See Order Notification Retry Policy for retry behavior.

Verifying Signatures

Validate callbacks using the signature header. Compute an HMAC-SHA256 using your secret key and the raw request body, then compare.

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'); 

Both order_broadcasted and order_cancelled are final states. An order cannot transition from completed to cancelled.

Callback Payloads

payment_pending

Order created, awaiting customer payment.

{
  "order_id": "9af6cd02-174f-438f-a362-fc6545ad125b",
  "external_transaction_id": null,
  "external_customer_id": null,
  "order_status": "payment_pending",
  "order_crypto": "LTC",
  "order_type": "buy",
  "order_crypto_amount": "0.070175135286017",
  "order_crypto_address": "ltc1q2k0xaafhgt3s8qw03wmajjmlc8gcepdy0un0ah",
  "order_crypto_tag": null,
  "order_amount_usd": 8.18,
  "order_amount_usd_plus_fees": 8.9,
  "order_amount_eur": 7.01,
  "order_amount_eur_plus_fees": 7.62,
  "network": "litecoin"
}

order_completed

Payment successful, crypto purchase processed.

{
  "order_id": "9fcc45a5-4def-4953-9bd8-9ff75d9aaa9c",
  "order_crypto_amount": 0.070175135286017,
  "order_crypto": "LTC",
  "order_status": "order_completed",
  "order_crypto_address": "ltc1qlec2yfpkdvn4lr0vpf27qggrxtu34zeu5l6g2u",
  "external_customer_id": "1234567",
  "order_amount_usd": "25",
  "order_amount_usd_plus_fees": "25.5",
  "order_amount_eur": "21",
  "order_crypto_tag": 12345,
  "order_amount_eur_plus_fees": "22.5",
  "network": "litecoin"
}

order_broadcasted

Transaction broadcast to blockchain.

{
  "order_id": "9fcc45a5-4def-4953-9bd8-9ff75d9aaa9c",
  "order_crypto_amount": 0.070309096973144,
  "order_crypto": "LTC",
  "order_status": "order_broadcasted",
  "transaction_id": "ea458dda0ff8583199bdd4d9b9a69a2813694764a633fd40b27de22a868cebec",
  "order_crypto_address": "ltc1qlec2yfpkdvn4lr0vpf27qggrxtu34zeu5l6g2u",
  "external_customer_id": "1234567",
  "order_amount_usd": "25",
  "order_amount_usd_plus_fees": "25.5",
  "order_amount_eur": "21",
  "order_crypto_tag": 12345,
  "order_amount_eur_plus_fees": "22.5",
  "network": "litecoin"
}

order_cancelled

Order cancelled (payment failure, user cancellation, etc.).

{
  "order_id": "9ab49879-92f0-44fc-992e-460285c879e8",
  "order_status": "order_cancelled",
  "order_type": "buy",
  "order_crypto": "LTC",
  "external_transaction_id": null,
  "external_customer_id": null
}

Response Fields

Field	Description
order_id	Swapped order ID
order_status	Current order state
order_crypto	Cryptocurrency code
order_crypto_amount	Crypto amount received
order_crypto_address	Destination wallet address
order_crypto_tag	Destination tag/memo (XRP, TON, etc.)
network	Blockchain network used
order_amount_usd	Crypto value in USD (mid-market rate, excludes fees)
order_amount_usd_plus_fees	USD amount including platform fee
order_amount_eur	Crypto value in EUR
order_amount_eur_plus_fees	EUR amount including platform fee
transaction_id	Blockchain transaction hash (broadcasted orders only)
external_customer_id	Your customer ID (if provided in URL)