Accept payments with hosted checkout
Checkout sessions in depth, from creating one to fulfilling the order.
A checkout session is a single-use Creddot payment page for one order. You create it on your server, redirect the customer, and confirm the payment. Creddot collects card details, so your servers never handle card numbers and stay out of PCI DSS scope.
Create a session
POST /checkout/sessions with the collections:create permission.
Prop
Type
Redirect the customer to checkoutUrl from the response.
Session states
GET /checkout/sessions/{id or your reference} returns the session and its status:
| Status | Meaning |
|---|---|
OPEN | Waiting for payment. A failed attempt keeps it open so the customer can try again. |
PAID | A payment succeeded. The session no longer accepts payments. |
EXPIRED | expiresAt passed without a successful payment. Create a new session to retry. |
CLOSED | Disabled without a successful payment. |
payment holds the successful payment, or the latest attempt while the session is open, with its Creddot id, reference, status, channel and feeMinor.
Confirm before you fulfil
Fulfil the order only after one of these, and make fulfilment idempotent because you may see both:
- A
transaction.successwebhook whosedata.merchantReferenceis your order reference. GET /checkout/sessions/{reference}returningPAID.
Then check that the amount and currency match what you charged.
const res = await fetch(`https://api.creddot.com/api/v1/checkout/sessions/${encodeURIComponent(reference)}`, {
headers: { 'x-api-key': process.env.CREDDOT_API_KEY, 'x-api-secret': process.env.CREDDOT_API_SECRET },
});
const session = await res.json();
if (session.status === 'PAID' && session.amountMinor === order.totalKobo && session.currency === 'NGN') {
await markOrderPaid(order.id, session.payment.id); // safe to call twice
}Finding the payment later
Payments made through a session get a Creddot reference starting with pl_. You don't need to store it: GET /transactions/by-reference/{your reference} finds the session's payment for you.
Good to know
- Each session takes one successful payment. Create a new session for every order or retry after expiry.
- Reusing a
referencereturns409. Use the samex-idempotency-keywhen retrying a create after a timeout. - Payment methods shown on checkout follow your settings in the dashboard.