API Reference

Full reference for the SwapSS Pay REST API. All merchant endpoints require Authorization: Bearer sspay_sec_test_demo_xxxxxxx. Base URL: https://swapss.lol

Download Postman collection

Authentication

Pass your secret API key in the Authorization header on every request. Keys are created in the cabinet under Settings → API Keys.

http

Authorization: Bearer sspay_sec_test_demo_abcdef
# Alternative header (same effect):
X-Merchant-API-Key: sspay_sec_test_demo_abcdef

Keys carry scopes (invoices.write, payouts.read, etc.). A request using a key that lacks the required scope returns 403 MISSING_SCOPE. See the authentication guide for the full scope table.

Idempotency

All POST creation endpoints require an Idempotency-Key header. Send any string (UUID v4 recommended, max 128 chars). Retrying with the same key returns the original response without creating a duplicate resource.

http

Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Keys are retained for 24 hours. Sending the same key with a different body returns 422 IDEMPOTENCY_KEY_REUSED_DIFFERENT_BODY. Full guide: Idempotency.

Rate limits

Scope	Default limit	Configurable?
Per API key	60 req / min	Yes, higher on request
Per IP (hosted checkout)	30 req / min	No

Exceeded requests get 429 with a Retry-After header (seconds). Repeated invalid-secret attempts on the same key trigger a temporary lockout that surfaces as 429 API_KEY_LOCKED with a Retry-After header; back off when you see it.

Errors

Every error uses the same envelope:

json

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "human-readable description",
    "request_id": "uuid-for-support"
  }
}

HTTP	Meaning
`200 / 201`	Success. `201` on resource creation.
`400`	Invalid input, missing field, business-rule violation (see `code`).
`401`	Missing or invalid API key.
`403`	Valid key but wrong scope, IP not in allowlist, or account suspended.
`404`	Resource not found (or belongs to a different merchant).
`409`	Conflict: duplicate `order_id`, invoice not cancellable, etc.
`422`	Idempotency key reused with different body.
`429`	Rate limit exceeded. Check `Retry-After`.
`500`	Unexpected server error. Log `request_id` and contact support.
`503`	Transient unavailability; retry shortly.

Full error code catalog: Error codes.

Pagination

List endpoints (GET /invoices, GET /payouts, etc.) use cursor-based pagination.

bash

# First page
curl "https://swapss.lol/api/v1/merchant/invoices?limit=50" \
  -H "Authorization: Bearer sspay_sec_test_demo_YOUR_KEY"

# Next page — pass cursor from previous response
curl "https://swapss.lol/api/v1/merchant/invoices?limit=50&cursor=eyJpZCI6Ik..." \
  -H "Authorization: Bearer sspay_sec_test_demo_YOUR_KEY"

json

{
  "data": [...],
  "meta": {
    "cursor": "eyJpZCI6Ik...",
    "has_more": true,
    "limit": 50,
    "total": 214
  }
}

Maximum page size is 200. Omit cursor to start from the most recent items. has_more: false means you’ve reached the end.

Deprecation headers

When an endpoint or parameter is scheduled for removal, responses include:

http

X-Swap-Pay-Tombstone-Warnings: field 'legacy_amount' deprecated; use 'amount' instead
Sunset: Sat, 01 Nov 2026 00:00:00 GMT
Deprecation: true

Log and monitor these headers in your integration. The Sunset date is the earliest date the endpoint or field may stop working.