Checkout Sessions

Checkout sessions can expose fee quotes so hosted checkout shows subtotal, processing fees, and total due before payment confirmation.

Ikawaari Checkout combine une famille de routes de checkout session authentifiée avec une famille de routes checkout publiques utilisées par l’expérience de checkout hébergé.

Familles de routes implémentées

Routes authentifiées :

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

Routes checkout publiques utilisées par la page hébergée :

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

Créer une checkout session

POST /api/v1/checkout/sessions

Authentification :

• ApiKey ou AppToken
• scope d’écriture pour les paiements

Exemple :

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"
    }
  }'

Paramètre	Type	Requis	Description
amount	integer:int64	Non	Montant de la session dans la plus petite unité monétaire.
currency	string	Non	Devise de la session, par exemple XOF.
country	string	Non	Code pays de la session.
paymentMethodTypes	string[]	Non	Méthodes à proposer dans la page checkout.
successUrl	string	Non	URL appelée après succès.
cancelUrl	string	Non	URL appelée après annulation.
customerEmail	string	Non	Email client prérempli ou associé à la session.
customerPhone	string	Non	Téléphone client prérempli ou associé à la session.
paymentLinkId	string:uuid	Non	Lien de paiement source, si la session vient d’un Payment Link.
paymentLinkV2Id	string:uuid	Non	Lien de paiement V2 source.
deferPaymentIntentCreation	boolean	Non	Diffère la création du PaymentIntent jusqu’au paiement.
metadata	object<string,object>	Non	Métadonnées de session.

Récupérer une checkout session

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

Utilisez cette route pour récupérer l’objet session autoritatif après sa création.

Flux de checkout hébergé public

Le frontend checkout utilise des routes publiques sous api/checkout.

Obtenir les détails de session pour la page hébergée

GET /api/checkout/{sessionId}

Soumettre le paiement depuis la page hébergée

POST /api/checkout/{sessionId}/pay

Cette route est publique car elle est consommée par la page de checkout elle-même, et non par les backends marchands.

Paramètre	Type	Description
session_id	string	Identifiant de session transmis par la page checkout.
return_url	string	URL de retour pour les flux redirigés.
payment_method.type	string	Type de méthode, par exemple mobile_money ou card.
payment_method.mobile_money.country	string	Code pays mobile money.
payment_method.mobile_money.operator	string	Opérateur mobile money.
payment_method.mobile_money.phone_number	string	Numéro mobile money.
payment_method.mobile_money.preferred_flow	string	Flux préféré lorsque le provider le supporte.
payment_method.card.token	string	Token de carte.
collected.amount	integer:int64	Montant collecté si la session autorise une valeur dynamique.
collected.customerDetails	object	Données client collectées par la page.
collected.customFields	object	Champs personnalisés collectés par la page.

Réponse typique

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

Redirigez le client vers url pour finaliser le paiement.

Note d’intégration

Ne documentez pas le checkout comme étant uniquement /api/v1/checkout/sessions.

L’expérience implémentée utilise à la fois :

• la création et la récupération marchandes authentifiées via api/v1/checkout/sessions
• les opérations publiques de checkout hébergé via api/checkout/*

Modes de checkout

Mode	Description
payment	Paiement ponctuel
subscription	Abonnement récurrent

Sections liées

• Payment Links
• Payment Intents
• Familles de routes