Hosted checkout

A checkout session is a payment page we host for you. The customer chooses their country and operator, types their number, confirms, and comes back to your site. You write no front end.

1. Create a session (server side)

curl https://api.patronise.me/v1/checkout-sessions \
  -H "Authorization: Bearer $PATRONISE_SECRET_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XAF",
    "description": "Order #1042",
    "reference": "order-1042",
    "success_url": "https://shop.example.com/orders/1042/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "metadata": { "order_id": "1042" }
  }'

Field	Description
`amount`, `currency`	Required.
`description`	Shown at the top of the page.
`reference`, `metadata`	Copied onto the payment.
`success_url`	Where the customer goes after paying. We add `?payment=pay_…`.
`cancel_url`	The "Cancel" link.
`fee_bearer`	`merchant` or `customer`.
`countries`	Limit the page to some countries, e.g. `["CM", "GA"]`.
`customer_email`	Pre-filled.
`expires_in_minutes`	10 to 1440. Default 60.

The response contains a url. Redirect the customer to it.

A publishable key (pk_…) may also create checkout sessions, so a static site can call this endpoint from the browser. It cannot read payments or move money.

2. Confirm the payment

When the customer pays, you receive payment.succeeded and checkout_session.completed. The checkout_session field of the payment holds the session id.

The redirect to success_url is not proof of payment: anyone can open that URL. Fulfil the order from the webhook, or check GET /v1/payments/{id} before you do.

Session states

open → complete once a payment succeeds, or expired when expires_at passes. A session takes only one successful payment.