> For the complete documentation index, see [llms.txt](https://docs.swapped.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapped.com/swapped-ramp/off-ramp-integration/order-notifications.md).

# Order Notifications

To receive order notifications, you can either provide a <mark style="color:red;">`responseUrl`</mark> per order or define a merchant-level webhook on the “Developers” page within the [**Swapped.com Dashboard**](https://dashboard.swapped.com/developers). 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](https://dashboard.swapped.com/developers), 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, <mark style="color:red;">you</mark> <mark style="color:red;"></mark><mark style="color:red;">**must**</mark> <mark style="color:red;"></mark><mark style="color:red;">validate that a transaction has not been credited</mark> before crediting it.

For more information on notification resending, see the [Order Notification Retry Policy](https://docs.swapped.com/#order-notification-retry-policy).

### Callback examples:

#### Payment Pending:

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

```json
{
  "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.

```json
{
  "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",
  "transaction_id": "C2237DF9D3268F715A80E48BF20D860C495B9726F28097A9AA18399F49BB7342"
}
```

#### Order Completed:

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

```json
{
  "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",
  "transaction_id": "C2237DF9D3268F715A80E48BF20D860C495B9726F28097A9AA18399F49BB7342"
}
```

#### Order Cancelled:

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

```json
{
  "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:

* <mark style="color:red;">`order_id`</mark>: The order ID on Swapped.com.
* <mark style="color:red;">`order_crypto_amount`</mark>: The exact cryptocurrency amount you will receive.
* <mark style="color:red;">`order_crypto`</mark>: The cryptocurrency you receive.
* <mark style="color:red;">`order_status`</mark>: The current status of the order.
* <mark style="color:red;">`order_crypto_address`</mark>: The cryptocurrency address where you receive the cryptocurrency.
* <mark style="color:red;">`external_customer_id`</mark>: Your customer's ID (If provided in the URL).
* <mark style="color:red;">`order_amount_usd`</mark>: The <mark style="color:orange;">`order_crypto_amount`</mark> converted to USD (Mid-market rates without spread). This does not include the platform fee.
* <mark style="color:red;">`order_crypto_tag`</mark>: The destination tag/memo of the order (often used with e.g. XRP or TON)
* <mark style="color:red;">`order_amount_usd_plus_fees`</mark>: The <mark style="color:red;">`order_amount_usd`</mark> plus the platform fee.
* <mark style="color:red;">`network`</mark>: The network used to send transactions.
* <mark style="color:red;">`order_type`</mark>: Indicator if the order is a buy or sell order.
* <mark style="color:red;">`transaction_id`</mark>: The crypto transaction hash.

### 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:

<mark style="color:red;">`payment_pending`</mark> →<mark style="color:red;">`order_processing`</mark>→<mark style="color:red;">`payout_pending`</mark>→ <mark style="color:red;">`order_completed`</mark>

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

<mark style="color:red;">`payment_pending`</mark> → <mark style="color:red;">`order_cancelled`</mark>

Both <mark style="color:red;">`order_completed`</mark> and <mark style="color:red;">`order_cancelled`</mark> are final states that correspond to a finalized swapped.com order ID. This means that an order will **never** go from a <mark style="color:red;">completed</mark> to a <mark style="color:red;">cancelled</mark> 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:

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.swapped.com/swapped-ramp/off-ramp-integration/order-notifications.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.