Skip to content
swapspay Developers
BUILD WITH SWAPSPAY

Your checkout.
Crypto, connected.

Go live with a plugin or build your own payment flow. Create a link, send your customer to checkout, and fulfil when their payment is confirmed.

01One payment, one address

A fresh deposit address for each payment request.

02Confirmation built in

Track the blockchain without asking for a transaction ID.

03Your order stays connected

A unique Payment ID alongside your order reference.

01

A few steps to your first payment

  1. Create your account. Sign up with your business details and website. Verify your email and set up your authenticator in Security.
  2. Create a live API key. Open API & integrations in your merchant workspace. Use a dedicated key for each integration and save it securely on your server.
  3. Check the connection. Make the request below. A successful response includes ok: true, mode: "live" and the key's payment permissions.
Check your connectioncURL
curl https://swapspay.io/api/v1/connection \
  -H 'Authorization: Bearer YOUR_API_KEY'
Keep the key on your server.

API keys can create and read payments for their assigned website. They cannot withdraw funds or manage your account. Never expose a key in browser JavaScript, mobile bundles or a public repository.

The website you provide at signup is saved in your workspace. Choose it for your API key; incoming payments are then attributed automatically. Sending another website ID in a payment request does not change that attribution.

02

Prefer a plugin? Connect WooCommerce.

Swapspay supports both classic checkout and Checkout Blocks. Your customers select crypto at checkout and complete payment on a hosted Swapspay page.

  1. Download the plugin from Integrations. In WordPress, open Plugins → Add New → Upload Plugin, install the ZIP and activate it.
  2. In WooCommerce → Settings → Payments → Swapspay, paste the dedicated API key for your store and enable the gateway.
  3. For signed updates, add https://your-store.com/wp-json/swapspay/v1/webhook in your Swapspay webhook settings. Save the matching signing secret in the gateway. Polling also works without webhooks.
  4. Place a small live order and confirm its status updates in both WooCommerce and Swapspay before opening the payment method to customers.

Orders stay on hold until sufficient funds are confirmed. WordPress cron checks pending orders approximately once a minute for up to seven days; schedule a server cron for reliable checks on stores with low traffic. Late or partial payments may need review.

The plugin does not support automatic refunds or recurring subscription billing. It has no withdrawal permissions. Keep the same API key while order creation is being reconciled.

03

Create a payment link

POST/api/v1/paymentsAuthenticated

Send your order reference and invoice amount as JSON. Every create request needs an Idempotency-Key: reuse the same key and body if a request times out.

Create a paymentcURL
curl https://swapspay.io/api/v1/payments \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: invoice-1042-attempt-1' \
  -d '{
    "reference": "INV-1042",
    "amount": "12.34",
    "currency": "USD",
    "description": "Invoice payment"
  }'
Payment request fields
FieldFormatDetails
returnUrlString · optionalHTTPS order-confirmation URL. When a website is assigned, the origin must match. Checkout redirects here only after payment is paid. Include it when creating the payment.
referenceString · requiredYour order reference, up to 120 characters.
amountDecimal string · requiredPositive amount with up to two decimal places, such as "12.34".
currencyString · optionalDefaults to USD. Available currencies: GET /api/config.
descriptionString · optionalA customer-facing description, up to 500 characters.

The converted USD value must be between $0.01 and $1,000,000. Non-USD invoices convert once when created. USDC and USDT are quoted at exactly one token per USD: a $12.34 invoice requests 12.34 USDC or USDT.

Response excerpt201 Created
{
  "payment": {
    "paymentId": "SP-0123456789ABCDEF0123",
    "mode": "live",
    "reference": "INV-1042",
    "invoiceCurrency": "USD",
    "invoiceAmount": "12.34",
    "usdCents": 1234,
    "status": "created"
  },
  "url": "https://swapspay.io/pay/<checkout-token>",
  "trackingUrl": "https://swapspay.io/track?id=SP-0123456789ABCDEF0123"
}

Save the returned Payment ID with your order, then redirect your customer to url. They select an available asset and network and receive their unique deposit address. Keep the checkout URL private to that customer.

One retry, one payment.

A successful first request returns 201; repeating its idempotency key and body returns 200. A changed body with that key returns 409. Keys are scoped to an API key, so reconcile uncertain requests before rotating it.

04

Know when it's paid

GET/api/v1/payments/{paymentId}Authenticated

Retrieve the latest payment using its Payment ID. The response has the same shape as payment creation, with the current status and checkout details. Poll from your server every 30–60 seconds, or use signed webhooks.

Check payment statuscURL
curl https://swapspay.io/api/v1/payments/SP-0123456789ABCDEF0123 \
  -H 'Authorization: Bearer YOUR_API_KEY'
Fulfil on confirmed payment.

Require payment.mode === "live" and payment.status === "paid". Match the Payment ID, order reference, invoice amount and currency to your stored order. A redirect or customer screenshot is not payment confirmation.

Payment statuses
StatusWhat it means
createdPayment link ready; the customer has not selected an asset.
allocatingA unique deposit address is being prepared.
awaiting_paymentThe address and amount are ready for the customer.
confirmingThe payment has been seen and needs network confirmations.
paidSufficient confirmed funds arrived within the quote window.
underpaidLess than the requested amount has arrived.
expired, underpaid_expiredThe quote window ended. Review any partial funds before resolving the order.
late_payment, allocation_reviewThe payment needs review; do not automatically fulfil.
cancelledThe payment was cancelled before address allocation.

Payment IDs are separate from your order numbers. Customers can return to payment tracking with their ID; public tracking shows only the ID, status, mode and creation time.

05

Receive signed payment updates

Add an HTTPS endpoint on your saved website's hostname in Webhooks. Save the one-time whsec_ signing secret on your server. Redirects and private network addresses are not supported.

Delivery headersHTTP
Swapspay-Event-Id: SE-1234
Swapspay-Timestamp: 1700000000
Swapspay-Signature: v1=<hex-hmac-sha256>

Verify HMAC-SHA256 over the exact bytes of timestamp + "." + rawRequestBody, using the entire signing-secret string as the key. Compare in constant time and reject timestamps more than 300 seconds from your server's clock. Parse JSON only after verifying the original request bytes.

Signature verificationNode.js
import { createHmac, timingSafeEqual } from 'node:crypto';

function validWebhook(secret, timestamp, signature, rawBody) {
  if (!/^\d+$/.test(timestamp || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  if (!/^v1=[0-9a-f]{64}$/.test(signature || '')) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody) // Buffer from the unmodified HTTP request
    .digest();
  return timingSafeEqual(expected, Buffer.from(signature.slice(3), 'hex'));
}

Events include id, type, createdAt and payment metadata. Treat delivery as at least once: deduplicate by event ID and allow for out-of-order updates. Return a 2xx response after saving the event durably, then retrieve the current payment through the API before fulfilment.

Failed delivery is retried with backoff for up to eight attempts. You can review and retry failed deliveries in the workspace. A connection-test webhook is only a connectivity check and must never trigger fulfilment.

06

Handle the edges

HTTP errors
CodeNext step
400Correct the request fields using the returned error message.
401Check the Bearer key is valid and has not been revoked.
403Check account access, email verification and authenticator setup.
404Check the Payment ID and that it belongs to this key's website.
409Resolve the idempotency conflict; avoid creating a duplicate payment.
410Retired test keys cannot be used; create a live key in the workspace.
429, 5xxBack off and retry. For creation, keep the original idempotency key and body.

Rate limits are 60 requests per minute per API key and 180 API requests per minute per IP. Keep idempotency keys between 1 and 120 characters. Save your Payment ID before processing status updates.

READY WHEN YOU ARE

Connect your first payment.

Your website, your orders, one merchant workspace.

Create your account