4 endpoints

Direct checkout

The calls the payment page makes itself: session verification, card submission, 3-D Secure return.

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

In plain English

Your own card form, driven step by step.

When to use it

Only if you build your own card form. These endpoints are not authenticated by your API key but by the session, and they put you inside the card-data compliance perimeter.

How to integrate it

1Grab the session id and the one-time verification key (vk) — returned by the create-session response, or carried by the payUrl redirect — then verify the session with that pair to get the display context: the vk is consumed by that verification.
2Submit the card data with that key — never with your API key.
3Follow the 3-D Secure redirect if the bank requires it, then confirm the return.
4Poll the payment status for display, and wait for the webhook for the business decision.

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/checkout/verifyVerify a checkout session
POST/checkout/submitSubmit card details for a checkout session
POST/checkout/returnConfirm the 3-D Secure return
GET/checkout/payments/{reference}Get buyer-facing payment status

POST200

Verify a checkout session

Opens a payment session for payment using its sessionId and the verify key (vk) from the create-session response. Returns the amount, currency, branding and capabilities of the session. Verify MUST be called before submit; on a single-use session the vk is consumed by the first verify and cannot be replayed. No API key — do not send X-CHARI-PAY-API-KEY.

Schema · CheckoutVerifyRequest

Field	Type	In	Required	Description
`sessionId`	string	body	Required	Session id from the create-session response.
`vk`	string	body	Required	Verify key (verifyKey) from the create-session response; single-use on single-use sessions.

POST200

Submit card details for a checkout session

Pays a verified session with a card, server-to-server (no hosted page). Preconditions: verify must have been called first; when the session was created with keepAlive=true, savePaymentMethodConsent=true is required; the Idempotency-Key header is required for a reusable (non single-use) session. Returns a terminal status, or PENDING_3DS with a redirectionUrl the buyer must open to complete the 3-D Secure challenge — afterwards call POST /checkout/return. Callers handling raw card data are responsible for their own PCI DSS compliance. No API key — do not send X-CHARI-PAY-API-KEY.

Schema · CheckoutSubmitRequest

Field	Type	In	Required	Description
`Idempotency-Key`	string	header	Optional	Required for a reusable session; optional (recommended) for a single-use one. Replaying the same key returns the first result.
`sessionId`	string	body	Required	Session id of an already-verified session.
`card`	Card	body	Required
`card.firstName`	string	body	Required
`card.lastName`	string	body	Required
`card.pan`	string	body	Required	Full card number (PAN). Never stored unmasked.
`card.expiryDate`	string	body	Required	Card expiry, MM/YY.
`card.cvv`	string	body	Required
`card.cardName`	string	body	Optional	Name as printed on the card.
`savePaymentMethodConsent`	boolean	body	Optional	Explicit buyer consent to store the payment method; required (true) when the session has keepAlive=true, ignored otherwise.

POST200

Confirm the 3-D Secure return

Correlates the buyer's return from the 3-D Secure challenge with the submitted operation and returns the final status plus the merchant accept/decline redirectUrl. Call it after the buyer completes the redirectionUrl from submit. No API key.

Schema · CheckoutReturnRequest

Field	Type	In	Required	Description
`sessionId`	string	body	Required
`operationId`	integer (int64)	body	Required

GET200

Get buyer-facing payment status

Resolves the status of a payment by order reference, payment-link reference, or the provider gateway id from the 3-D Secure return. Always answers with our reference and carries no PII. Use it to poll for the outcome after submit/return. No API key.

Field	Type	In	Required	Description
`reference`	string	path	Required	Order reference, payment-link reference, or provider gateway id.

Talk to an integrator

A question about integration?

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