Comment utiliser le checkout hébergé ?

Le checkout hébergé est l’intégration recommandée pour la plupart des équipes. Votre serveur crée une session, le client paie sur une page hébergée par lomi., puis votre système confirme le résultat.

Quand utiliser le checkout hébergé ?

Utilisez-le si vous voulez :

• Une page de paiement complète avec plusieurs moyens de paiement.
• Moins de travail UI et conformité dans votre propre application.
• Un flux clair avec URL de succès et d’annulation.
• Un checkout basé sur un montant ou sur un produit.
• Un chemin fiable de la sandbox vers le live.

Créer une session de paiement

Votre serveur appelle POST /checkout-sessions et redirige le client vers checkout_url.

Référence API (schéma complet) : Créer une session de checkout

Champs essentiels :

Passez metadata pour vos propres identifiants de commande. Voir la page API pour tous les champs optionnels.

Produits « payez ce que vous voulez »

Lorsque product_id ou price_id pointe vers un tarif avec pricing_model: pay_what_you_want :

• Omettre amount: la session utilise le prix unitaire suggéré (amount sur le tarif) × quantity.
• Fournir amount: doit être un sous-total valide : prix unitaire dans [minimum_amount, maximum_amount] × quantity. Le serveur rejette les valeurs hors bornes.
• Tunnel hébergé: l’acheteur peut modifier le prix unitaire avant de payer ; validation côté client et serveur.
• Flux programmatiques: définissez amount à la création de session si le total est déjà connu.

Panier multi-produits (line_items)

Avec line_items, chaque ligne doit référencer un tarif ponctuel en tarification standard (fixe). L’API renvoie 400 avec l’un des codes :

Produits récurrents (abonnements)

Lorsque product_id désigne un produit récurrent :

• Omettre amount: la session utilise le prix catalogue du price_id choisi (la quantité n’est pas multipliée pour les abonnements).
• Fournir amount: doit correspondre au prix récurrent catalogue pour la validation (sauf prorata au moment du paiement ; voir Comportement du tunnel: Abonnements).
• Essai ou inscription non_initial: le client peut payer 0 au tunnel, mais la session enregistre souvent le prix catalogue pour que create_checkout_session respecte amount > 0. N’envoyez pas amount: 0 sans vous appuyer sur le calcul produit.
• La finalisation crée un abonnement (webhook SUBSCRIPTION_CREATED), pas seulement une transaction ponctuelle.

Exemple :

const subscriptionSession = await lomi.checkoutSessions.create({
  product_id: 'prod_recurring_abc...',
  price_id: 'price_monthly_xyz...',
  currency_code: 'XOF',
  customer_email: 'customer@example.com',
  success_url: 'https://your-site.com/welcome',
  allow_coupon_code: true,
});

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

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_SECRET_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',
});

// Produit PWYW avec montant personnalisé et quantité
const pwywSession = await lomi.checkoutSessions.create({
  product_id: 'prod_tip_jar...',
  currency_code: 'XOF',
  amount: 1500,
  quantity: 2,
  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_SECRET_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"
    }
})

# Produit PWYW avec montant personnalisé et quantité
pwyw_session = client.checkout_sessions.create({
    "product_id": "prod_tip_jar...",
    "currency_code": "XOF",
    "amount": 1500,
    "quantity": 2,
    "success_url": "https://your-site.com/success"
})

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

curl -X POST "https://api.lomi.africa/checkout-sessions" \
  -H "X-API-KEY: $LOMI_SECRET_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"
}

Intégrer sans redirection

Pour garder le client sur votre page, utilisez le SDK embed avec le même checkout_url :

import { loadLomiCheckout } from '@lomi./embed';

loadLomiCheckout({
  checkoutUrl: session.checkout_url,
  mode: 'modal',
  onComplete: (payload) => console.log(payload.transactionId),
});

Voir Widget de paiement intégré pour modal, inline et self-hosted.

Confirmer le paiement

Les redirections servent à l’expérience client, pas à la réconciliation finale. Votre serveur doit s’appuyer sur les webhooks ou une lecture API côté serveur avant de livrer une commande.

Vérifiez :

• Le statut de la session de checkout.
• Le statut de la transaction liée.
• Le montant, la devise, le client et les métadonnées.
• La signature webhook et l’ID d’événement.

Variantes courantes

Lister et récupérer les sessions

Utilisez la référence API pour lister ou récupérer une session par ID :

• Lister les sessions
• Obtenir une session

Webhooks

Les webhooks sortants marchands (lomi. appelle votre URL) utilisent l’énumération webhook_event documentée dans Webhooks. Le champ HTTP `event` et l’en-tête `X-Lomi-Event` reprennent ces valeurs (par ex. `PAYMENT_SUCCEEDED`).

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

Il n’existe pas de valeur séparée `checkout.session.*` dans l’énumération `webhook_event`. 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

API liée

• Créer une session de checkout
• Lister les sessions
• Obtenir une session
• Comportement checkout
• Webhooks