Skip to main content
POST
/
api
/
canary
/
checkout
/
sessions
Create Hosted Checkout
curl --request POST \
  --url http://localhost:3000/api/canary/checkout/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "currency": "<string>",
  "metadata": {
    "orderId": "ORD-12345",
    "source": "web"
  },
  "merchantId": "<string>",
  "customerId": "<string>",
  "productId": "<string>",
  "lineItems": [
    {
      "amount": 123,
      "currency": "<string>",
      "productId": "<string>",
      "quantity": 123
    }
  ],
  "totalAmount": 123,
  "mode": "<string>"
}
'
{
  "id": "checkout_sess_123",
  "merchantId": "merchant_456",
  "customerId": "customer_789",
  "sessionUrl": "https://pay.cashful.africa/?op=checkout&sessionId=checkout_sess_123",
  "successUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "lineItems": [
    {
      "productId": "product_001",
      "quantity": 2,
      "amount": 5000,
      "currency": "ZAR"
    },
    {
      "productId": "product_002",
      "quantity": 1,
      "amount": 3000,
      "currency": "ZAR"
    }
  ],
  "totalAmount": 13000,
  "currency": "ZAR",
  "mode": "payment",
  "status": "active",
  "expiresAt": "2025-01-17T10:30:00.000Z",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Checkout session details

successUrl
string
required

The URL to redirect to on successful payment

cancelUrl
string
required

The URL to redirect to if customer cancels

currency
string
required

The three-letter ISO 4217 currency code

metadata
object
required

Optional custom metadata

Example:
{ "orderId": "ORD-12345", "source": "web" }
merchantId
string

The ID of the merchant whose balance is being requested. If omitted, defaults to the authenticated merchant.

customerId
string

The unique identifier of the customer

productId
string

The unique identifier of the product

lineItems
object[]

Array of line items for the checkout

totalAmount
number

The total amount in the smallest currency unit

mode
string

The checkout mode (e.g., 'payment')

Response

Checkout session created successfully

id
string
required

Unique identifier

createdAt
string<date-time>
required
updatedAt
string<date-time>
required
merchantId
string
required
sessionUrl
string
required
successUrl
string
required
cancelUrl
string
required
currency
string
required
status
string
required
metadata
object
required
Example:
{ "orderId": "ORD-12345" }
deletedAt
string<date-time>
customerId
string
lineItems
object[]
totalAmount
number
mode
string
expiresAt
string<date-time>