> 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/readme/order-notifications.md).
# Order Notifications
To receive order notifications. Configure a callback URL either per-order through **`responseUrl`** or at the merchant level via the [Swapped Dashboard](https://dashboard.swapped.com/developers).
### 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.
{% hint style="warning" %}
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.](/misc/order-notification-retry-policy.md)
{% endhint %}
### 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:**
{% code overflow="wrap" %}
```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');
```
{% endcode %}
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.
```json
{
"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.
```json
{
"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.
```json
{
"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.).
```json
{
"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) |
---
# 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/readme/order-notifications.md?ask=&goal=
```
`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.