Checkout Sessions

A Checkout Session creates a payment page hosted on checkout.sangho.ga. Your customer is redirected to this page, completes their payment there, and is then sent back to your success_url. You never handle payment data directly — Sangho takes care of it.

This is the recommended integration for e-commerce sites and web applications: zero PCI DSS scope on your side, customizable to your brand colors from your dashboard.

Lifecycle

open→processing→complete→expired / payment_failed

Status	Meaning
open	Session created — payment page accessible.
processing	Payment submitted, processing in progress.
complete	Payment successful — customer redirected to success_url.
expired	Session expired without payment (deadline passed or /expire/ called).
payment_failed	Payment attempt failed — session remains open for retry.

Modes

Mode	Usage
payment	One-time payment — standard flow. Creates a PaymentIntent.
subscription	Recurring subscription. Creates a Subscription.
setup	Saves a payment method without an immediate charge.

Endpoints

Méthode	Endpoint	Description
POST	/checkout-sessions/	Create a session
GET	/checkout-sessions/	List sessions
GET	/checkout-sessions/{id}/	Retrieve a session
POST	/checkout-sessions/{id}/expire/	Manually expire a session

Is this introduction clear?

UtileÀ améliorer

Object schema

ResponseCheckoutSession object

jsonCopier

{
  "id": "sess_xxxxxxxxxxxx",
  "object": "checkout_session",
  "mode": "payment",
  "status": "open",
  "currency": "XAF",
  "amount_total": 25000,
  "amount_subtotal": 25000,
  "payment_intent": null,
  "customer": "cust_xxxxxxxx",
  "customer_email": "client@email.com",
  "url": "https://checkout.sangho.ga/c/sess_xxx",
  "success_url": "https://boutique.com/merci?session={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://boutique.com/panier",
  "line_items": [
    {
      "product": "prod_xxx",
      "description": "Formation Excel Avancé",
      "quantity": 1,
      "unit_amount": 25000,
      "amount_total": 25000
    }
  ],
  "payment_method_types": ["mobile_money", "bank_card"],
  "expires_at": "2026-03-01T10:30:00Z",
  "livemode": true,
  "metadata": {},
  "created_at": "2026-03-01T10:00:00Z"
}

Create a Checkout Session

Creates a payment session and returns the URL of the hosted payment page (url). Redirect your customer to this URL immediately.

POSTRequest body

success_urlRequis

stringHTTPS URLex :https://boutique.com/merci?session={CHECKOUT_SESSION_ID}

Redirect URL after a successful payment. Sangho automatically replaces {CHECKOUT_SESSION_ID} with the session ID — use it to verify the payment server-side.

💡

Always verify server-side that the session is indeed in complete status before delivering the product or service. Never trust the redirect alone — a user could manipulate the URL.

line_itemsRequis

array[object]

Order line items. Each object contains product (ID) or description + unit_amount, plus quantity (integer, default 1).

💡

For Products with a free-form price (price_type: free), you must provide the unit_amount in the line item to override the default price. Maximum 20 line items per session.

currencyRequis

stringISO 4217

Currency code for the session. All line items are billed in this currency.

modeOptionnel

stringdéfaut :payment

Session mode: payment, subscription, or setup.

▸En savoir plus

💡

In subscription mode, the session creates a Subscription object and charges the customer according to the plan’s recurrence. In setup mode, no charge is made — the method is saved for future use.

customerOptionnel

stringcust_...

ID of an existing Customer to associate with the session. The payment page is pre-filled with their information.

▸En savoir plus

💡

Mutually exclusive with customer_email. If neither is provided, Sangho creates an anonymous Customer at the time of payment if collect_customer_info: true.

customer_emailOptionnel

stringemail

Email pre-filled in the payment page form. Sangho automatically creates or finds the corresponding Customer.

cancel_urlOptionnel

stringHTTPS URL

Redirect URL if the buyer clicks “Cancel” or closes the payment page.

▸En savoir plus

💡

If not provided, a generic back button is displayed. Recommended: point to the cart or the product page to reduce abandonment.

payment_method_typesOptionnel

array[string]

Payment methods offered on the checkout page. If omitted, all of the App’s active methods are available.

expires_inOptionnel

integersecondsdéfaut :1800

Validity duration of the session in seconds from its creation.

▸En savoir plus

💡

Minimum: 300 seconds (5 min). Maximum: 86,400 seconds (24h). Past this delay, the payment page displays an expiration message and the session moves to expired. An expired session cannot be reactivated — create a new one.

metadataOptionnel

object

Free-form data associated with the session. Returned in the checkout.session.completed webhook.

Server-side verification required

After redirecting to success_url, always call GET /checkout-sessions/{id}/ server-side to confirm that status === ‘complete’ before delivering your product. Never grant delivery based on the URL redirect alone.

Are the Checkout Session parameters clear?

UtileÀ améliorer

Create a session and redirect

cURLNode JSPythonPHP

bashCopier

curl -X POST https://api.sangho.ga/v1/checkout-sessions/ \
  -H "Authorization: Bearer sk_prod_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://boutique.com/merci?session={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://boutique.com/panier",
    "currency": "XAF",
    "line_items": [
      { "product": "prod_xxx", "quantity": 1 },
      { "product": "prod_yyy", "quantity": 2 }
    ],
    "customer_email": "client@email.com",
    "expires_in": 3600
  }'

Response201 Created

The session is open. Redirect your customer to session.url immediately. The session expires after expires_in seconds.

jsonCopier

{
  "id": "sess_xxxxxxxxxxxx",
  "object": "checkout_session",
  "status": "open",
  "currency": "XAF",
  "amount_total": 75000,
  "url": "https://checkout.sangho.ga/c/sess_xxx",
  "expires_at": "2026-03-01T11:00:00Z",
  "livemode": true,
  "created_at": "2026-03-01T10:00:00Z"
}

ResponseComplete session (verification)

Call GET /checkout-sessions/{id}/ server-side after redirection to confirm payment. Only deliver if status === complete.

jsonCopier

{
  "id": "sess_xxxxxxxxxxxx",
  "status": "complete",
  "amount_total": 75000,
  "payment_intent": "pi_xxxxxxxxxxxx",
  "customer": "cust_xxxxxxxx",
  "currency": "XAF",
  "updated_at": "2026-03-01T10:04:00Z"
}