Skip to main content
POST
/
api
/
canary
/
checkout
/
sessions
Create Hosted Checkout
curl --request POST \
  --url https://api.cashful.africa/api/canary/checkout/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchantId": "<string>",
  "currency": "<string>",
  "metadata": {
    "orderId": "ORD-12345",
    "source": "web"
  }
}
'
{
  "id": "checkout_sess_123",
  "merchantId": "merchant_456",
  "paymentIntentId": "pi_123456789",
  "customerId": "customer_789",
  "sessionUrl": "https://pay.cashful.africa/?entityType=checkout&entityId=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": "open",
  "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

merchantId
string
required

The ID of the merchant for the checkout session.

currency
string
required

The three-letter ISO 4217 currency code

metadata
object
required

Optional custom metadata

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

The unique identifier of the customer

productId
string

The unique identifier of the product

successUrl
string

The URL to redirect to on successful payment

cancelUrl
string

The URL to redirect to on cancel

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')

hostedCheckoutConfig
object

Configuration for the hosted checkout page

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
currency
string
required
status
string
required
metadata
object
required
Example:
{ "orderId": "ORD-12345" }
deletedAt
string<date-time>
paymentIntentId
string
customerId
string
successUrl
string
cancelUrl
string
lineItems
object[]
totalAmount
number
mode
string
expiresAt
string<date-time>
hostedCheckoutConfig
object

Configuration for the hosted checkout page