Create a hosted checkout session

curl --request POST \ --url https://sandbox.api.eqxpay.io/v1/checkout/sessions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "market": "MW", "amount": 5000, "currency": "MWK", "reference": "INV-2026-001", "success_url": "https://shop.example.com/checkout/success", "description": "Payment for Order #123", "metadata": { "order_id": "ORD-123" }, "cancel_url": "https://shop.example.com/checkout/cancel", "logo_url": "https://cdn.example.com/logo.png", "primary_color": "#FF5733" } '

{ "session_id": "e3d4b5c6-...", "integrator_id": "f1a2b3c4-...", "market": "MW", "amount": 5000, "currency": "MWK", "reference": "INV-2026-001", "success_url": "https://shop.example.com/checkout/success", "session_token": "a1b2c3d4e5f6...", "checkout_url": "https://checkout.eqx.io/a1b2c3d4e5f6...", "status": "active", "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z", "expires_at": "2023-11-07T05:31:56Z", "description": "Payment for Order #123", "metadata": { "order_id": "ORD-123" }, "cancel_url": "https://shop.example.com/checkout/cancel", "merchant_name": "Acme Corp", "logo_url": "https://cdn.example.com/logo.png", "primary_color": "#FF5733", "market_name": "Malawi", "collection_id": null }

Authorizations

Authorization

string

header

required

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

Body

application/json

market

string

required

Market code (e.g. MW for Malawi)

Example:

"MW"

amount

number

required

Amount in minor currency units (e.g. MWK tambala)

Example:

5000

currency

string

required

Example:

"MWK"

reference

string

required

Integrator reconciliation reference

Example:

"INV-2026-001"

success_url

string

required

Example:

"https://shop.example.com/checkout/success"

description

string

Human-readable description shown on checkout page

Example:

"Payment for Order #123"

metadata

object

Arbitrary metadata forwarded to the bound collection

Example:

{ "order_id": "ORD-123" }

cancel_url

string

Example:

"https://shop.example.com/checkout/cancel"

logo_url

string

HTTPS URL to the integrator logo shown on the checkout page

Example:

"https://cdn.example.com/logo.png"

primary_color

string

Hex color override for the checkout card primary accent (e.g. #FF5733)

Example:

"#FF5733"

Response

session_id

string

required

Example:

"e3d4b5c6-..."

integrator_id

string

required

Example:

"f1a2b3c4-..."

market

string

required

Example:

"MW"

amount

number

required

Example:

5000

currency

string

required

Example:

"MWK"

reference

string

required

Example:

"INV-2026-001"

success_url

string

required

Example:

"https://shop.example.com/checkout/success"

session_token

string

required

Opaque checkout session token (64 hex chars)

Example:

"a1b2c3d4e5f6..."

checkout_url

string

required

Example:

"https://checkout.eqx.io/a1b2c3d4e5f6..."

status

string

required

active | collection_bound | expired | cancelled

Example:

"active"

created_at

string<date-time>

required

updated_at

string<date-time>

required

expires_at

string<date-time>

required

description

object

Example:

"Payment for Order #123"

metadata

object

Example:

{ "order_id": "ORD-123" }

cancel_url

object

Example:

"https://shop.example.com/checkout/cancel"

merchant_name

object

Snapshotted from partner account display name at session creation

Example:

"Acme Corp"

logo_url

object

Example:

"https://cdn.example.com/logo.png"

primary_color

object

Example:

"#FF5733"

market_name

object

Example:

"Malawi"

collection_id

object

Example:

null