Checkouts

Direct payment checkout sessions that support both hosted pages and custom integrations.

Create Checkout

Create a checkout session for accepting payments.

Endpoint: POST /v1/checkouts

Authentication: Required

Request Body:

Field	Type	Required	Description
`amount`	string	No*	Amount in decimal format (e.g., `"100.00"`). Optional if items provided.
`currency`	string	No	Currency code (default: `"GMD"`)
`items`	array	No	Itemized line items (if provided, amount is calculated from items)
`items[].product_id`	string	No	Product ID (optional)
`items[].description`	string	No	Item description
`items[].quantity`	integer	Yes	Item quantity
`items[].unit_price`	string	No	Unit price per item
`payment_method_types`	array	No	Restrict to specific payment methods (e.g., `["wave", "card"]`)
`automatic_payment_methods`	boolean	No	Auto-enable payment methods (default: `true`)
`payment_method`	string	No	Payment method to initialize with (`card`, `wave`, `afrimoney`, `qmoney`). When provided, checkout is ready immediately - no separate initialization needed.
`customer_id`	string	No	Link to existing customer
`customer_phone`	string	No	Customer phone number (prefill)
`customer_email`	string	No	Customer email address (prefill)
`customer_name`	string	No	Customer full name (prefill)
`expires_in`	integer	No	Session expiration in seconds (60-86400, default: 86400)
`metadata`	object	No	Custom metadata
`description`	string	No	Checkout description
`reference`	string	No	External reference ID
`idempotency_key`	string	No	Idempotency key to prevent duplicate checkouts
`success_url`	string	No	URL to redirect on successful payment
`failure_url`	string	No	URL to redirect on failed payment

*Either amount or items required

Example:

HTTP

TypeScript

Python

Success Response (201):

{
  "data": {
    "id": "cs_abc123",
    "amount": "100.00",
    "currency": "GMD",
    "status": "pending",
    "payment_url": "https://pay.jokoor.com/checkout/cs_abc123",
    "available_payment_methods": ["wave", "afrimoney", "card"],
    "automatic_payment_methods": true,
    "customer_id": null,
    "customer_phone": "",
    "customer_email": null,
    "customer_name": null,
    "expires_at": "2025-11-16T10:30:00Z",
    "description": "Service payment",
    "reference": null,
    "items": null,
    "metadata": {},
    "livemode": false,
    "transaction": null,
    "created_at": "2025-11-15T10:30:00Z"
  }
}

How Checkouts Work

Create a checkout session, redirect customer to payment_url, and receive payment confirmation via webhook or status check.

Without `payment_method` - Less Control, More Flexibility

When you create a checkout without payment_method, the customer chooses the payment method on the hosted payment page.

Control what methods are available:

TypeScript

Python

Best for:

You want customer to choose their preferred method

Simple integration with hosted payment page

All-in-one payment link (share the URL with customer)

With `payment_method` - More Control, Direct Flow

When you create a checkout with payment_method specified, you get a payment URL ready for that specific method immediately.

No customer choice - direct to payment:

TypeScript

Python

Supported methods:

wave - Wave Mobile Money

card - Credit/debit cards with custom form

afrimoney - Afrimoney Mobile Money

Best for:

You have "Pay with Wave" / "Pay with Card" buttons

You know the payment method upfront

Building custom payment flows

Faster checkout (one less step for customer)

Quick Comparison

Feature	Without payment_method	With payment_method
Control level	Less (customer chooses)	More (you decide)
payment_url	Payment method selection page	Ready for specific method
Customer experience	Choose method → Pay	Pay immediately
Method restrictions	`payment_method_types` or dashboard	Single method only
Use case	Flexible, all-in-one payment link	Direct, "Pay with X" buttons

Get Checkout

Get details of a specific checkout session.

Endpoint: GET /v1/checkouts/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "cs_abc123",
    "amount": "100.00",
    "currency": "GMD",
    "status": "pending",
    "payment_url": "https://pay.jokoor.com/checkout/cs_abc123",
    "available_payment_methods": ["wave", "afrimoney", "card"],
    "automatic_payment_methods": true,
    "customer_id": null,
    "customer_phone": "",
    "customer_email": null,
    "customer_name": null,
    "expires_at": "2025-11-16T10:30:00Z",
    "description": "Service payment",
    "reference": null,
    "items": null,
    "metadata": {},
    "livemode": false,
    "transaction": null,
    "created_at": "2025-11-15T10:30:00Z"
  }
}

Cancel Checkout

Cancel a pending checkout session.

Endpoint: POST /v1/checkouts/{id}/cancel

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "chk_abc123",
    "status": "cancelled",
    "cancelled_at": "2024-01-15T11:00:00Z"
  }
}

Checkouts

Checkouts#

Create Checkout#

How Checkouts Work#

Without payment_method - Less Control, More Flexibility#

With payment_method - More Control, Direct Flow#

Get Checkout#

Cancel Checkout#

Checkouts

Create Checkout

How Checkouts Work

Without `payment_method` - Less Control, More Flexibility

With `payment_method` - More Control, Direct Flow

Get Checkout

Cancel Checkout