Sessions de paiement

L’API Checkout Sessions permet de créer des sessions temporaires et sécurisées pour les paiements clients. Redirigez votre client vers le tunnel de paiement hébergé par lomi. pour finaliser le paiement.

Pour les règles transverses (codes promo, lignes, devise, lien avec l’état du paiement), voir Comportement du tunnel.

Les sessions de paiement expirent par défaut après 60 minutes.

Créer une session de paiement

Crée une session et renvoie une URL pour rediriger le client.

Corps de la requête

Champ	Type	Obligatoire	Description
`amount`	`number`	Non*	Montant à encaisser. Facultatif si `product_id` est fourni.
`currency_code`	`string`	Oui	Code devise (`XOF`, `USD`, `EUR`)
`title`	`string`	Non	Titre affiché sur le tunnel
`description`	`string`	Non	Description de l’achat
`customer_id`	`string`	Non	Identifiant client existant
`customer_email`	`string`	Non	E-mail (préremplit le formulaire)
`customer_name`	`string`	Non	Nom (préremplit le formulaire)
`customer_phone`	`string`	Non	Téléphone (préremplit le formulaire)
`product_id`	`string`	Non	ID produit (montant calculé à partir du tarif)
`price_id`	`string`	Non	Tarif précis si le produit en a plusieurs
`subscription_id`	`string`	Non	ID d’abonnement pour renouvellements ou modifications
`quantity`	`number`	Non	Quantité (défaut : `1`)
`allow_quantity`	`boolean`	Non	Autoriser le client à modifier la quantité
`success_url`	`string`	Non	URL de redirection après paiement réussi
`cancel_url`	`string`	Non	URL de redirection si le paiement est annulé
`allow_coupon_code`	`boolean`	Non	Autoriser les codes de réduction (défaut : `false`)
`require_billing_address`	`boolean`	Non	Exiger l’adresse de facturation (défaut : `true`)
`payment_link_id`	`string`	Non	ID du lien de paiement associé
`metadata`	`object`	Non	Paires clé-valeur personnalisées

*amount est requis sauf si product_id est fourni.

import { LomiSDK } from '@lomi./sdk';

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_API_KEY!,
  environment: 'live',
});

// Tunnel simple avec montant
const session = await lomi.checkoutSessions.create({
  amount: 10000,
  currency_code: 'XOF',
  title: 'Order #12345',
  description: 'Paiement des articles du panier',
  customer_email: 'customer@example.com',
  success_url: 'https://your-site.com/success',
  cancel_url: 'https://your-site.com/cancel',
  metadata: {
    order_id: 'ORD-12345',
  },
});

// Tunnel basé sur un produit
const productSession = await lomi.checkoutSessions.create({
  product_id: 'prod_abc123...',
  currency_code: 'XOF',
  quantity: 2,
  allow_coupon_code: true,
  success_url: 'https://your-site.com/success',
});

console.log(`Redirect to: ${session.checkout_url}`);

from lomi import LomiClient
import os

client = LomiClient(
    api_key=os.environ["LOMI_API_KEY"],
    environment="test"
)

session = client.checkout_sessions.create({
    "amount": 10000,
    "currency_code": "XOF",
    "title": "Order #12345",
    "description": "Payment for items in cart",
    "customer_email": "customer@example.com",
    "success_url": "https://your-site.com/success",
    "cancel_url": "https://your-site.com/cancel",
    "metadata": {
        "order_id": "ORD-12345"
    }
})

print(f"Redirect to: {session['checkout_url']}")

curl -X POST "https://api.lomi.africa/checkout-sessions" \
  -H "X-API-KEY: $LOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency_code": "XOF",
    "title": "Order #12345",
    "description": "Payment for items in cart",
    "customer_email": "customer@example.com",
    "success_url": "https://your-site.com/success",
    "cancel_url": "https://your-site.com/cancel",
    "metadata": {
      "order_id": "ORD-12345"
    }
  }'

Réponse

{
  "id": "cs_abc123...",
  "checkout_url": "https://checkout.lomi.africa/cs_abc123...",
  "status": "open",
  "amount": 10000,
  "currency_code": "XOF",
  "title": "Order #12345",
  "customer_email": "customer@example.com",
  "expires_at": "2024-01-15T11:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Lister les sessions de paiement

Récupère les sessions avec filtrage optionnel.

Paramètres de requête

Paramètre	Type	Description
`status`	`string`	Filtrer par statut : `open`, `completed`, `expired` (correspond à `checkout_session_status` en base)
`limit`	`number`	Résultats par page (défaut : `20`)
`offset`	`number`	Décalage pagination (défaut : `0`)

const sessions = await lomi.checkoutSessions.list({
  status: 'open',
  limit: 20,
});

sessions = client.checkout_sessions.list(status="open", limit=20)

curl -X GET "https://api.lomi.africa/checkout-sessions?status=open&limit=20" \
  -H "X-API-KEY: $LOMI_API_KEY"

Obtenir une session de paiement

Récupère le détail d’une session.

const session = await lomi.checkoutSessions.get('cs_abc123...');
console.log(`Status: ${session.status}`);

session = client.checkout_sessions.get('cs_abc123...')
print(f"Status: {session['status']}")

curl -X GET "https://api.lomi.africa/checkout-sessions/cs_abc123..." \
  -H "X-API-KEY: $LOMI_API_KEY"

Objet session de paiement

Champ	Type	Description
`id`	`string`	Identifiant unique de session
`checkout_url`	`string`	URL de redirection client
`status`	`string`	`open`, `completed`, `expired`
`amount`	`number`	Montant à encaisser
`currency_code`	`string`	Code devise
`title`	`string`	Titre de session
`description`	`string`	Description
`customer_id`	`string`	Identifiant client associé
`customer_email`	`string`	E-mail client
`product_id`	`string`	ID produit associé
`transaction_id`	`string`	Transaction créée après succès
`metadata`	`object`	Métadonnées personnalisées
`expires_at`	`string`	Horodatage d’expiration
`created_at`	`string`	Horodatage de création

Webhooks

Il existe deux niveaux distincts de « webhooks » dans le code de l’API :

Webhooks entrants prestataires (reçus par lomi.) : Wave et les gestionnaires façon Stripe utilisent des chaînes de type événement façon Stripe dans le corps JSON, par ex. checkout.session.completed, checkout.session.payment_failed, checkout.session.expired. Ces routes figurent sous OpenAPI → Webhooks - Providers (par ex. `POST /webhooks/wave`, `POST /webhooks/stripe`). Ce ne sont pas les noms d’événements que vous passez dans `authorized_events` sur votre propre point de terminaison.
Webhooks sortants marchands (lomi. appelle votre URL) : les abonnements utilisent l’énumération Postgres webhook_event, le même jeu que dans Webhooks. Le champ HTTP `event` et l’en-tête `X-Lomi-Event` reprennent ces valeurs (par ex. `PAYMENT_SUCCEEDED`), comme dans `WebhookSenderService.prepareWebhookPayload` dans `apps/api`.

Pour les résultats de tunnel côté votre serveur, souscrivez au minimum à :

Valeur `authorized_events`	Déclenchement
`PAYMENT_SUCCEEDED`	Paiement terminé ; le corps `data` suit la forme transaction (voir Webhooks).
`PAYMENT_FAILED`	Tentative échouée (y compris certains chemins d’échec prestataire).

Il n’existe pas de valeur séparée `checkout.session.*` dans l’énumération `webhook_event` (apps/api/src/utils/types/api.ts reflète le type base). L’expiration de session sans paiement réussi se voit sur les enregistrements session et transaction (statut `expired` par ex.) ; utilisez `GET /checkout-sessions/{id}` ou une liste avec `status=expired` / `completed` plutôt qu’un webhook marchand nommé comme checkout.session.expired.

Réponses d’erreur

Statut	Description
`400`	Entrée invalide ou erreur de validation
`401`	Clé API invalide ou manquante
`404`	Session introuvable ou accès refusé

Sessions de paiement

Sur cette page