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)