Checkout Sessions

Ikawaari Checkout combines an authenticated checkout session route family with a public checkout route family used by the hosted checkout experience.

Implemented route families

Authenticated routes:

• POST /api/v1/checkout/sessions
• GET /api/v1/checkout/sessions/{id}

Public checkout routes used by the hosted page:

• GET /api/checkout/{sessionId}
• POST /api/checkout/{sessionId}/pay

Create a checkout session

POST /api/v1/checkout/sessions

Authentication:

• ApiKey or AppToken
• write scope for payments

Example:

curl -X POST https://api.ikawaari.com/api/v1/checkout/sessions \
  -H "Authorization: Bearer ik_test_or_app_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "XOF",
    "country": "SN",
    "paymentMethodTypes": ["mobile_money", "card"],
    "successUrl": "https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancelUrl": "https://yoursite.com/cancel",
    "customerEmail": "customer@example.com",
    "metadata": {
      "order_id": "order_123"
    }
  }'

Parameter	Type	Required	Description
amount	integer:int64	No	Session amount in the smallest currency unit.
currency	string	No	Session currency, for example XOF.
country	string	No	Session country code.
paymentMethodTypes	string[]	No	Methods to show on the checkout page.
successUrl	string	No	URL called after success.
cancelUrl	string	No	URL called after cancellation.
customerEmail	string	No	Customer email to prefill or attach to the session.
customerPhone	string	No	Customer phone to prefill or attach to the session.
paymentLinkId	string:uuid	No	Source payment link if the session comes from a Payment Link.
paymentLinkV2Id	string:uuid	No	Source V2 payment link.
deferPaymentIntentCreation	boolean	No	Defers PaymentIntent creation until payment.
metadata	object<string,object>	No	Session metadata.

Retrieve a checkout session

GET /api/v1/checkout/sessions/{id}

Use this route to retrieve the authoritative session object after creation.

Public hosted checkout flow

The checkout frontend uses public routes under api/checkout.

Get session details for the hosted page

GET /api/checkout/{sessionId}

Submit payment from the hosted page

POST /api/checkout/{sessionId}/pay

This route is public because it is consumed by the checkout page itself, not by merchant backends.

Parameter	Type	Description
session_id	string	Session ID submitted by the checkout page.
return_url	string	Return URL for redirected flows.
payment_method.type	string	Method type, for example mobile_money or card.
payment_method.mobile_money.country	string	Mobile money country code.
payment_method.mobile_money.operator	string	Mobile money operator.
payment_method.mobile_money.phone_number	string	Mobile money number.
payment_method.mobile_money.preferred_flow	string	Preferred flow when supported by the provider.
payment_method.card.token	string	Card token.
collected.amount	integer:int64	Collected amount when the session allows a dynamic value.
collected.customerDetails	object	Customer details collected by the page.
collected.customFields	object	Custom fields collected by the page.

Typical response

{
  "id": "cs_abc123",
  "url": "https://pay.ikawaari.com/cs_abc123",
  "status": "open",
  "payment_intent": "pi_xyz789",
  "expires_at": 1708387200
}

Redirect the customer to url to complete the payment.

Integration note

Do not document checkout as only /api/v1/checkout/sessions.

The implemented experience uses both:

• authenticated merchant creation and retrieval via api/v1/checkout/sessions
• public hosted checkout operations via api/checkout/*

Checkout modes

Mode	Description
payment	One-time payment
subscription	Recurring subscription

Related sections

• Payment Links
• Payment Intents
• Route Families