Merchant API

1. 01

   Get keys

   Apply at Merchant, then make a test key (sk_test_) under Developers.

2. 02

   Create a checkout

   One call with the price and your order number. Send the buyer to its url.

3. 03

   Hear it was paid

   Set a webhook address. Check its signature, then fulfil the order on checkout.paid.

curl -X POST https://spotex.trade/api/merchant/v1/checkout-sessions \
  -H "Authorization: Bearer $SPOTEX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1043" \
  -d '{ "amount_usd": "25.00", "item": "Gift box",
        "order_id": "1043",
        "return_url": "https://yourshop.com/thanks" }'

With a test key that is all real except the money: open the session's url, press Pay in full, and your webhook gets checkout.paid with "livemode": false.

• Node.js

  TypeScript types, no dependencies

  npm install github:SpotEx-trade/spotex-pay-nodeREADME and examples on GitHub

• Python

  Standard library only, 3.8+

  pip install git+https://github.com/SpotEx-trade/spotex-pay-pythonREADME and examples on GitHub

• PHP

  PHP 7.4+, curl

  composer config repositories.spotex vcs https://github.com/SpotEx-trade/spotex-pay-php && composer require spotex/payREADME and examples on GitHub

• Every key can create and read checkouts and read your balance. Nothing more unless you choose it.
• Transfer and withdraw are separate permissions, off unless you tick them. A key with either must have an IP allowlist: requests from any other address are refused.
• A withdraw key can be whitelist-only: it then sends only to addresses on your withdrawal whitelist, which you add in the Merchant Center with the identity check.
• A test key (sk_test_…) works in test mode. It can never pay out.
• Revoke a key and it stops working at once. Keys see only your own merchant account. Keep them on your server, never in a web page or an app.
• 300 requests a minute per key; past that, 429 with a Retry-After header.

curl -X POST https://spotex.trade/api/merchant/v1/checkout-sessions \
  -H "Authorization: Bearer $SPOTEX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1043" \
  -d '{ "amount_usd": "25.00", "item": "Gift box",
        "order_id": "1043",
        "return_url": "https://yourshop.com/thanks" }'

• The buyer chooses a coin and pays from their SpotEx balance or any wallet, then gets a button back to return_url, which must be on your website.
• A session takes one payment and closes once paid, or after expires_in_minutes (default 60, up to 1440). The webhook's checkout carries session_id and your order_id.
• Payments start at $1 from a SpotEx balance and $5 from a wallet, up to $5,000.

curl -X POST https://spotex.trade/api/merchant/v1/checkouts \
  -H "Authorization: Bearer $SPOTEX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1043" \
  -d '{ "amount_usd": "25.00", "coin": "DOGE",
        "item": "Gift box", "order_id": "1043" }'

{
  "id": "cm...",
  "object": "checkout",
  "livemode": true,
  "status": "pending",
  "method": "onchain",
  "item": "Gift box",
  "order_id": "1043",
  "amount_usd": "25.00",
  "coin": "DOGE",
  "amount": "138.88888889",
  "rate_usd": "0.18",
  "address": "D8x...",
  "received": "0",
  "confirming": "0",
  "remaining": "138.88888889",
  "expires_at": "2026-10-27T10:30:00.000Z",
  "hosted_url": "https://spotex.trade/checkout/cm...",
  ...
}

• Show address and amount (a QR code of the address helps), or send the buyer to hosted_url, SpotEx's own page for it.
• The price is held for 30 minutes. Coins that can be sent from any wallet are marked onchain: true in GET /coins.
• Paid in parts? SpotEx holds what arrived until the rest does (remaining says how much), or until you accept it as paid in the Merchant Center. Set a shortfall to accept (Settings, up to 5%) and a payment that short or less is paid on arrival.
• When paid, the amount less the 0.5% fee is in your merchant wallet: fee and net say what each was.
• Chose to receive payments as one coin (Settings)? Each payment in another coin is sold on the spot market as it lands, within 2% of the market price and with no trading fee, for 1% in all on what converts.

POST /your-webhook
SpotEx-Event: checkout.paid
SpotEx-Delivery: evt_8f1c...
SpotEx-Signature: t=1793071234,v1=5b2c...

{ "id": "evt_8f1c...", "type": "checkout.paid", "created": 1793071234,
  "livemode": true, "data": { "checkout": { ... } } }

Check the signature before trusting anything in the body: v1 is an HMAC-SHA256 of <t>.<raw body> with your webhook signing secret. Refuse events whose t is more than five minutes old, and treat the same id twice as one event.

import { constructEvent } from "spotex-pay";

// rawBody: the exact bytes received, before any JSON parsing
const event = constructEvent(rawBody, req.headers["spotex-signature"], secret);
if (event.type === "checkout.paid" && event.livemode) {
  fulfil(event.data.checkout.order_id); // once per event.id
}

The webhook address must be HTTPS on a public domain name, on port 443 or 8443. Redirects are not followed.

# Pay a SpotEx user (instant)
curl -X POST https://spotex.trade/api/merchant/v1/payouts/transfers \
  -H "Authorization: Bearer $SPOTEX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-1043" \
  -d '{ "to": "alice", "coin": "USDT", "amount": "25",
        "note": "Refund for order 1043" }'

# Withdraw on-chain
curl -X POST https://spotex.trade/api/merchant/v1/payouts/withdrawals \
  -H "Authorization: Bearer $SPOTEX_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: supplier-2026-10-27" \
  -d '{ "coin": "USDT", "network": "BSC",
        "address": "0x...", "amount": "250" }'

• Confirmed by your key alone: no email and no authenticator code.
• Sent automatically up to $1,000 a payout and $5,000 in 24 hours. Larger ones are accepted and wait for SpotEx to approve: a transfer is then pending_review, a withdrawal security_review. The amount is reserved in your wallet meanwhile.
• network is needed only for a coin sent on more than one chain. A withdrawal's network fee comes out of your wallet on top of amount.
• Transfers follow the rules for any transfer between accounts (the minimum amount, and transfers being switched on) and go to the same account up to 20 times a day.
• Payouts stop while SpotEx has withdrawals paused, for a frozen account, and for a while after a security change on your account.

Send an Idempotency-Key header (8 to 100 letters, digits, - or _): the same request with the same key returns the same checkout or payout, however often it is sent. It is required for payouts. After a timeout, retry with the same key, never a new one, or you may pay twice. The SDKs make one for you when you leave it out; for payouts, always pass your own.

{ "error": { "code": "insufficient_funds", "message": "Not enough USDT in the merchant wallet." } }

The SDKs raise these as an error with status, code and message, and a network failure or timeout as network_error.