Skip to main content
POST
https://api.swiftpay.cx
/
api
/
checkout
/
sessions
curl -X POST https://api.swiftpay.cx/api/checkout/sessions \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Coffee Subscription - Premium Package",
    "customer": {
      "email": "[email protected]"
    },
    "askShipping": true,
    "urls": {
      "success": "https://yoursite.com/success",
      "cancel": "https://yoursite.com/cancel",
      "failure": "https://yoursite.com/payment-failed"
    },
    "items": [
      {
        "name": "Premium Coffee Beans",
        "description": "Ethiopian Yirgacheffe - Light Roast",
        "price": 24.99,
        "quantity": 2,
        "imageUrl": "https://yoursite.com/images/coffee.jpg"
      },
      {
        "name": "Shipping",
        "description": null,
        "price": 5.00,
        "quantity": 1,
        "imageUrl": null
      }
    ],
    "metadata": {
      "orderId": "ORD-2026-12345",
      "subscriptionId": "sub_premium_monthly",
      "customerTier": "gold",
      "isFirstOrder": true,
      "referralCode": "FRIEND20"
    }
  }'
{
  "success": true,
  "data": {
    "id": "01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
    "businessId": "01936d2e-7a5b-7c8d-9e2f-3a4b5c6d7e8f",
    "userId": "01936d2e-6b4c-7d5e-8f9a-1b2c3d4e5f6a",
    "status": "pending",
    "currency": "USD",
    "total": 5998,
    "description": "Coffee Subscription - Premium Package",
    "customerEmail": "[email protected]",
    "askShipping": true,
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel",
    "failureUrl": "https://yoursite.com/payment-failed",
    "checkoutUrl": "https://swiftpay.cx/checkout/01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
    "metadata": {
      "orderId": "ORD-2026-12345",
      "subscriptionId": "sub_premium_monthly",
      "customerTier": "gold",
      "isFirstOrder": true,
      "referralCode": "FRIEND20"
    },
    "items": [
      {
        "id": "01936d2e-9a8b-7c6d-5e4f-3a2b1c0d9e8f",
        "sessionId": "01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
        "name": "Premium Coffee Beans",
        "description": "Ethiopian Yirgacheffe - Light Roast",
        "price": 2499,
        "quantity": 2,
        "imageUrl": "https://yoursite.com/images/coffee.jpg",
        "subtotal": 4998
      },
      {
        "id": "01936d2e-9b7c-8d5e-6f4a-3b2c1d0e9f8a",
        "sessionId": "01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
        "name": "Shipping",
        "description": null,
        "price": 500,
        "quantity": 1,
        "imageUrl": null,
        "subtotal": 500
      }
    ],
    "createdAt": "2026-01-10T16:30:00.000Z",
    "updatedAt": "2026-01-10T16:30:00.000Z",
    "completedAt": null
  }
}

Create Checkout Session

Creates a new checkout session that your customer can use to complete payment. The session includes line items, pricing, customer information, and redirect URLs.

Request

Authorization
string
required
Bearer token with your API key (format: Bearer mp_live_... or Bearer mp_test_...)
description
string
required
A description of the checkout session (1-256 characters), shown to the customer during checkout.
customer
object
required
askShipping
boolean
default:false
Whether to collect shipping address from the customer during checkout. Defaults to false.
urls
object
Redirect URLs for different payment outcomes. All URLs are optional and support null values.
items
array
required
List of items in the checkout. At least one item is required, maximum 100 items.
metadata
object | array
Flexible format: Can be either an object (key-value pairs) or an array of {key, value} objects.
  • Maximum 50 metadata entries
  • Keys: alphanumeric, dashes, underscores only (max 64 chars)
  • Values: string (max 255 chars), number (integer), or boolean
Object format (recommended for API calls):
{
  "orderId": "ORD-12345",
  "customerId": "CUST-789",
  "priority": 1,
  "isGift": false
}
Array format (used by frontend forms):
[
  { "key": "orderId", "value": "ORD-12345" },
  { "key": "priority", "value": 1 }
]

Response

success
boolean
Whether the request was successful
data
object
curl -X POST https://api.swiftpay.cx/api/checkout/sessions \
  -H "Authorization: Bearer mp_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Coffee Subscription - Premium Package",
    "customer": {
      "email": "[email protected]"
    },
    "askShipping": true,
    "urls": {
      "success": "https://yoursite.com/success",
      "cancel": "https://yoursite.com/cancel",
      "failure": "https://yoursite.com/payment-failed"
    },
    "items": [
      {
        "name": "Premium Coffee Beans",
        "description": "Ethiopian Yirgacheffe - Light Roast",
        "price": 24.99,
        "quantity": 2,
        "imageUrl": "https://yoursite.com/images/coffee.jpg"
      },
      {
        "name": "Shipping",
        "description": null,
        "price": 5.00,
        "quantity": 1,
        "imageUrl": null
      }
    ],
    "metadata": {
      "orderId": "ORD-2026-12345",
      "subscriptionId": "sub_premium_monthly",
      "customerTier": "gold",
      "isFirstOrder": true,
      "referralCode": "FRIEND20"
    }
  }'
{
  "success": true,
  "data": {
    "id": "01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
    "businessId": "01936d2e-7a5b-7c8d-9e2f-3a4b5c6d7e8f",
    "userId": "01936d2e-6b4c-7d5e-8f9a-1b2c3d4e5f6a",
    "status": "pending",
    "currency": "USD",
    "total": 5998,
    "description": "Coffee Subscription - Premium Package",
    "customerEmail": "[email protected]",
    "askShipping": true,
    "successUrl": "https://yoursite.com/success",
    "cancelUrl": "https://yoursite.com/cancel",
    "failureUrl": "https://yoursite.com/payment-failed",
    "checkoutUrl": "https://swiftpay.cx/checkout/01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
    "metadata": {
      "orderId": "ORD-2026-12345",
      "subscriptionId": "sub_premium_monthly",
      "customerTier": "gold",
      "isFirstOrder": true,
      "referralCode": "FRIEND20"
    },
    "items": [
      {
        "id": "01936d2e-9a8b-7c6d-5e4f-3a2b1c0d9e8f",
        "sessionId": "01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
        "name": "Premium Coffee Beans",
        "description": "Ethiopian Yirgacheffe - Light Roast",
        "price": 2499,
        "quantity": 2,
        "imageUrl": "https://yoursite.com/images/coffee.jpg",
        "subtotal": 4998
      },
      {
        "id": "01936d2e-9b7c-8d5e-6f4a-3b2c1d0e9f8a",
        "sessionId": "01936d2e-8f4a-7b3c-9e5f-2a1c8d9b6e3f",
        "name": "Shipping",
        "description": null,
        "price": 500,
        "quantity": 1,
        "imageUrl": null,
        "subtotal": 500
      }
    ],
    "createdAt": "2026-01-10T16:30:00.000Z",
    "updatedAt": "2026-01-10T16:30:00.000Z",
    "completedAt": null
  }
}

Notes

  • Pricing: All prices in the request are in dollars (e.g., 24.99), but returned amounts are in cents (e.g., 2499)
  • Metadata Formats: Both object and array formats are accepted. The API automatically normalizes array format to object format
  • URL Validation: All URLs are validated for security (only http:// and https:// schemes allowed, internal IPs blocked)
  • Rate Limiting: Standard tier allows 100 requests per minute
  • Idempotency: Not currently supported - each request creates a new session
  • Expiration: Sessions remain active until completed, failed, or cancelled (no automatic expiration)