💬Order Notifications

Need help with your integration? Click here to chat with our custom GPT for instant answers.

To receive order notifications, you can either provide a responseUrl per order or define a merchant-level webhook on the “Developers” page within the Swapped.com Dashboard. You will receive the notification via the provided URL. In the header of the HTTP request, there’s a signature to validate that the data comes from Swapped.com.

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

Callback Config Priority

The system follows a clear priority structure for determining where to send callbacks.

• If a responseURL is provided in the iframe initialization URL, this will be used as a priority.

• If a responseURL is not provided, but a callback URL is configured via the Swapped.com dashboard, this will be used.

• If neither responseURL nor callback URL is set, callbacks will be disabled for this order.

This configuration is locked in when the order is created and cannot be changed, even if you later update your merchant-level webhook settings.

Best Practices

Order notifications can be resent to account for network errors. As such, you must validate that a transaction has not been credited before crediting it.

For more information on notification resending, see the Order Notification Retry Policy.

Callback examples:

Payment Pending:

The transaction was created, but the payment is still incomplete.

{
  "order_id": "16a285c1-b04e-4b9f-b35d-a68fc292229e",
  "external_transaction_id": null,
  "external_customer_id": null,
  "order_status": "payment_pending",
  "order_crypto": "LTC",
  "order_type": "sell",
  "order_crypto_amount": "1.1880399307349",
  "order_crypto_address": "ltc1qgydf26ffh3zen6k75ye568rpqmes7fx4daqvrg",
  "order_crypto_tag": null,
  "order_amount_usd": 109.38,
  "order_amount_usd_plus_fees": 116.01,
  "order_amount_eur": 94.29,
  "order_amount_eur_plus_fees": 100,
  "network": "litecoin"
}

Payout pending:

Indicates that the cryptocurrency transaction has been confirmed on the chain and the payout to the user is pending.

{
  "order_id": "81f2fcff-a81c-4e5a-8377-14bbe23fb1ef",
  "external_transaction_id": null,
  "external_customer_id": null,
  "order_status": "payout_pending",
  "order_crypto": "SOL",
  "order_type": "sell",
  "order_crypto_amount": 0.060096622,
  "order_crypto_address": "7frXvz2EutQmsmX6mgFMTE9MPuLsSPT2mgEro2EzPoNz",
  "order_crypto_tag": null,
  "order_amount_usd": 10.21,
  "order_amount_usd_plus_fees": 10.45,
  "order_amount_eur": 8.8,
  "order_amount_eur_plus_fees": 9.01,
  "network": "solana"
}

Order Completed:

Indicates that the order has been processed, and the sale of cryptocurrency was successful.

{
  "order_id": "81f2fcff-a81c-4e5a-8377-14bbe23fb1ef",
  "external_transaction_id": null,
  "external_customer_id": null,
  "order_status": "order_completed",
  "order_crypto": "SOL",
  "order_type": "sell",
  "order_crypto_amount": "0.060096622",
  "order_crypto_address": "7frXvz2EutQmsmX6mgFMTE9MPuLsSPT2mgEro2EzPoNz",
  "order_crypto_tag": null,
  "order_amount_usd": 10.21,
  "order_amount_usd_plus_fees": 10.45,
  "order_amount_eur": 8.8,
  "order_amount_eur_plus_fees": 9.01,
  "network": "solana"
}

Order Cancelled:

Indicates that the order is cancelled for any reason, such as payment failure or user cancellation.

{
  "order_id": "16a285c1-b04e-4b9f-b35d-a68fc292229e",
  "external_transaction_id": null,
  "external_customer_id": null,
  "order_status": "order_cancelled",
  "order_crypto": "LTC",
  "order_type": "sell"
}

Response Definition:

• order_id: The order ID on Swapped.com.

• order_crypto_amount: The exact cryptocurrency amount you will receive.

• order_crypto: The cryptocurrency you receive.

• order_status: The current status of the order.

• order_crypto_address: The cryptocurrency address where you receive the cryptocurrency.

• external_customer_id: Your customer's ID (If provided in the URL).

• order_amount_usd: The order_crypto_amount converted to USD (Mid-market rates without spread). This does not include the platform fee.

• order_crypto_tag: The destination tag/memo of the order (often used with e.g. XRP or TON)

• order_amount_usd_plus_fees: The order_amount_usd plus the platform fee.

• network: The network used to send transactions.

• order_type: Indicator if the order is a buy or sell order.

Order State Flows

An order can follow one of two possible state flows:

Flow 1: This is applied when an order gets completed successfully and the user receives crypto:

payment_pending →order_processing→payout_pending→ order_completed

Flow 2: This occurs when an order gets cancelled for any reason, and the user does not receive crypto:

payment_pending → order_cancelled

Both order_completed and order_cancelled are final states that correspond to a finalized swapped.com order ID. This means that an order will never go from a completed to a cancelled state.

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