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.
A fresh deposit address for each payment request.
Track the blockchain without asking for a transaction ID.
A unique Payment ID alongside your order reference.
A few steps to your first payment
- Create your account. Sign up with your business details and website. Verify your email and set up your authenticator in Security.
- 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.
- Check the connection. Make the request below. A successful response includes
ok: true,mode: "live"and the key's payment permissions.
curl https://swapspay.io/api/v1/connection \
-H 'Authorization: Bearer YOUR_API_KEY'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.
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.
- Download the plugin from Integrations. In WordPress, open Plugins → Add New → Upload Plugin, install the ZIP and activate it.
- In WooCommerce → Settings → Payments → Swapspay, paste the dedicated API key for your store and enable the gateway.
- For signed updates, add
https://your-store.com/wp-json/swapspay/v1/webhookin your Swapspay webhook settings. Save the matching signing secret in the gateway. Polling also works without webhooks. - 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.
Create a payment link
/api/v1/paymentsAuthenticatedSend 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.
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"
}'| Field | Format | Details |
|---|---|---|
returnUrl | String · optional | HTTPS 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. |
reference | String · required | Your order reference, up to 120 characters. |
amount | Decimal string · required | Positive amount with up to two decimal places, such as "12.34". |
currency | String · optional | Defaults to USD. Available currencies: GET /api/config. |
description | String · optional | A 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.
{
"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.
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.
Know when it's paid
/api/v1/payments/{paymentId}AuthenticatedRetrieve 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.
curl https://swapspay.io/api/v1/payments/SP-0123456789ABCDEF0123 \
-H 'Authorization: Bearer YOUR_API_KEY'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.
| Status | What it means |
|---|---|
created | Payment link ready; the customer has not selected an asset. |
allocating | A unique deposit address is being prepared. |
awaiting_payment | The address and amount are ready for the customer. |
confirming | The payment has been seen and needs network confirmations. |
paid | Sufficient confirmed funds arrived within the quote window. |
underpaid | Less than the requested amount has arrived. |
expired, underpaid_expired | The quote window ended. Review any partial funds before resolving the order. |
late_payment, allocation_review | The payment needs review; do not automatically fulfil. |
cancelled | The 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.
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.
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.
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.
Handle the edges
| Code | Next step |
|---|---|
400 | Correct the request fields using the returned error message. |
401 | Check the Bearer key is valid and has not been revoked. |
403 | Check account access, email verification and authenticator setup. |
404 | Check the Payment ID and that it belongs to this key's website. |
409 | Resolve the idempotency conflict; avoid creating a duplicate payment. |
410 | Retired test keys cannot be used; create a live key in the workspace. |
429, 5xx | Back 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.
Connect your first payment.
Your website, your orders, one merchant workspace.