Skip to main content

​
API Reference

The SwiftPay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

​
Base URL

https://api.swiftpay.cx
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

​
Authentication

The SwiftPay API uses API keys to authenticate requests. Include your API key in the Authorization header: 
Authorization: Bearer mp_live_your_api_key
Keep your API keys secure. Do not share them in publicly accessible areas such as GitHub, client-side code, or in your documentation.

​
Request Format

For POST and PUT requests, include a Content-Type: application/json header and pass parameters as JSON in the request body. 
curl -X POST https://api.swiftpay.cx/api/checkout/sessions \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"amountInCents": 2999, "currency": "USD"}'

​
Response Format

All responses are returned as JSON objects with the following structure:

​
Success Response

{
   "success": true,
   "data": {
      // Response data here
   }
}

​
List Response

{
   "success": true,
   "data": {
      "items": [
         // Array of items
      ],
      "meta": {
         "total": 150,
         "page": 1,
         "limit": 20,
         "totalPages": 8,
         "hasNextPage": true,
         "hasPreviousPage": false
      }
   }
}

​
Error Response

{
   "success": false,
   "error": {
      "type": "validation_error",
      "message": "Human-readable error message",
      "requestId": "req_abc123"
   }
}

​
HTTP Status Codes

CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Server Error - Something went wrong

​
Pagination

List endpoints support cursor-based pagination:
ParameterTypeDescription
limitintegerNumber of results per page (default: 20, max: 100)
cursorstringCursor for the next page of results
# First page
curl "https://api.swiftpay.cx/api/checkout/sessions?limit=20" \
  -H "Authorization: Bearer mp_live_your_api_key"

# Next page
curl "https://api.swiftpay.cx/api/checkout/sessions?limit=20&cursor=cursor_abc123" \
  -H "Authorization: Bearer mp_live_your_api_key"

​
Rate Limiting

API requests are rate limited per API key:
TierRequests/MinBurst
Standard60120
Growth300600
EnterpriseCustomCustom
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1705315200

​
Idempotency

For POST requests, you can pass an Idempotency-Key header to ensure exactly-once delivery: 
curl -X POST https://api.swiftpay.cx/api/checkout/sessions \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"amountInCents": 2999, "currency": "USD"}'
Idempotency keys are cached for 24 hours.

​
Versioning

The current API version is v1. The version is included in the URL path: 
https://api.swiftpay.cx/api/v1/checkout/sessions
Currently, all routes are unversioned. Versioning will be introduced in future releases with backward compatibility.

​
Available Endpoints

​
Balance

​
Checkout Sessions

​
Refunds

​
Reserves

​
Withdrawals

​
Webhooks

​
SDKs

Official SDKs are coming soon for:
  • Node.js / TypeScript
  • Python
  • PHP
  • Go
  • Ruby
In the meantime, use the REST API directly with any HTTP client.