4 endpoints

Checkout sessions

An e-commerce order becomes a session: you redirect the buyer to the hosted checkout and collect the result.

Endpoint names and descriptions come from the OpenAPI contract, in English — they cannot drift from the API.

In plain English

Payment inside your site: one order, one session.

When to use it

For a shop or an app where payment sits inside an order funnel, with return and cancel URLs that belong to you. A session expires 72 hours after creation by default — use `expiresAt` to shorten that.

How to integrate it

1Create the session with the amount and your order reference — your return URLs are optional: without them, your account's defaults apply.
2Redirect the buyer to the checkout URL you get back.
3On their return, show a pending state — the redirect says the buyer came back, not that the payment succeeded.
4Confirm the order when the webhook arrives, never on the redirect alone.

Sandbox test card

The sandbox runs on real rails against a test environment: the flows are genuine, the money is not. Only one card is accepted there.

Only this PAN is accepted. Any other number — including the 4242… cards from other platforms — is rejected upstream, usually with a 502 and the stable BAAS_CHARI_ERROR code. If you hit that error while testing, check the card number you entered first.

POST/v1/payment-sessions/{sessionId}/cancelCancel a checkout session
GET/v1/payment-sessionsList checkout sessions
POST/v1/payment-sessionsCreate a checkout session
GET/v1/payment-sessions/{sessionId}Retrieve a checkout session

POST

Cancel a checkout session

Expires the session so it can no longer be paid. Returns the updated session status.

Field	Type	In	Required	Description
`sessionId`	string	path	Required

GET

List checkout sessions

Returns the caller's checkout sessions for the key's environment, most recent first. Optionally filter by creation origin with ?origin=API or ?origin=DASHBOARD.

Field	Type	In	Required	Description
`origin`	enum	query	Optional	Filter by creation origin (API or DASHBOARD).Values `APIDASHBOARD`
`pageable`	Pageable	query	Required

POST200

Create a checkout session

Creates a single-use checkout session for an order and returns its hosted checkoutUrl. Supply an optional client-owned externalId (unique per merchant) to make the create idempotent: a duplicate externalId returns the existing session with 200 OK. Pass an optional Idempotency-Key header to make retries safe.

Schema · CreateCheckoutSessionRequest

Field	Type	In	Required	Description
`Idempotency-Key`	string	header	Optional	Optional idempotency key; replaying the same value returns the first result.
`amount`	number	body	Required	Amount to collect, in MAD major units.
`orderId`	string	body	Required	Your order/business reference for this checkout.
`singleUse`	boolean	body	Optional	Single-use session (recommended). Defaults to true.
`externalId`	string	body	Optional	Optional client-supplied id, unique per merchant; a duplicate value replays the existing session. Distinct from orderId/externalReference, which are not uniqueness-enforced.
`config`	CheckoutSessionConfig	body	Required	Buyer, redirect URLs and options for the checkout.
`config.customer`	CheckoutSessionCustomer	body	Required	The buyer being charged.
`config.urls`	CheckoutSessionUrls	body	Optional	Optional redirect / notification URLs. Any field left unset falls back to the merchant's configured default, then the platform default.
`config.keepAlive`	boolean	body	Optional	Keep the session alive after a failed attempt so the buyer can retry. Defaults to false.
`config.frontend`	CheckoutSessionFrontend	body	Optional	Optional branding for the hosted checkout page.
`config.settlement`	CheckoutSessionSettlement	body	Optional	Optional distribution — sub-merchant wallet to credit.
`metadata`	object	body	Optional	Free-form metadata object (≤ 4 KB) echoed back in the payment webhook.
`expiresAt`	string (date-time)	body	Optional	Session expiry (ISO-8601 UTC). Must be in the future; defaults to 72h after creation.
`notifyOnFailure`	boolean	body	Optional	Also send a payment.failed webhook when the payment fails. Defaults to false.

GET

Retrieve a checkout session

Fetches a session's current status, amount and expiration by its id.

Field	Type	In	Required	Description
`sessionId`	string	path	Required	Session id.

Talk to an integrator

A question about integration?

Our technical team supports integrators from the first sandbox call through to go-live.