💬Order Notifications

Swapped Pay Webhook Responses

To receive order notifications for Swapped Pay, 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": "SP-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": "SP-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": "SP-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": "SP-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": "SP-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 Pay

• 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 Pay 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