# Parcours d’intégration
Source: https://docs.lomi.africa/start/integration-journey

De la sandbox au live : compte, clés, premier paiement, webhooks et mise en production.

***

title: 'Parcours d’intégration'
description: 'De la sandbox au live : compte, clés, premier paiement, webhooks et mise en production.'
docType: tutorial
-----------------

import { DocsAgentIndex } from '@/components/docs/docs-agent-index';

<DocsAgentIndex />

Le checkout hébergé, les liens de paiement, les abonnements et les autres produits ci-dessous passent tous par la même API marchande. Le choix de **ce que vous construisez** est indépendant de **comment vous utilisez lomi.** : API, SDK, CLI ou MCP.

## Dans la sandbox

* Payer avec des [cartes de test](/start/sandbox-payments)
* Laisser Wave et MTN se compléter automatiquement avec une clé test
* Envoyer `X-Scenario-Key: pending` ou `failed` sur les charges Wave/MTN directes
* Transférer les webhooks avec `lomi listen`

## En live, vous ne pouvez pas

* Auto-compléter le Mobile Money (le client doit approuver sur l’appareil)
* Utiliser les PAN de test (ils ne fonctionnent qu’avec une clé test)

## Comment utiliser lomi.

Choisissez la surface qui correspond à votre façon de travailler.

<IntegrationSurfaceGroup id="how-you-call-lomi">
  <IntegrationSurface transport="api" title="Appeler le contrat HTTP directement" identifier="POST /checkout-sessions" href="/api" hrefLabel="Ouvrir la référence API">
    Utilisez l’API quand vous voulez la requête et la réponse exactes, un langage sans SDK officiel, ou comparer avec l’OpenAPI. Envoyez votre clé secrète en `X-API-Key` (`LOMI_SECRET_KEY`). `Idempotency-Key` est obligatoire sur les écritures qui déplacent de l’argent.

    Créer un checkout sandbox :

    ```bash
    curl -sS -X POST "https://sandbox.api.lomi.africa/checkout-sessions" \
      -H "X-API-Key: $LOMI_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 10000,
        "currency_code": "XOF",
        "title": "Commande de test",
        "success_url": "https://example.com/success",
        "cancel_url": "https://example.com/cancel"
      }'
    ```

    Ouvrez `checkout_url` dans la réponse et payez avec un [moyen de test sandbox](/start/sandbox-payments). Parcours complet : [Comment tester un paiement ?](/start/first-payment). Détail de l’endpoint : [Créer une session checkout](/api/checkout-sessions/CheckoutSessionsController_create).
  </IntegrationSurface>

  <IntegrationSurface transport="sdk" title="Appeler lomi. depuis votre code" identifier="@lomi./sdk" href="/start/sdk-quickstart" hrefLabel="Ouvrir le guide SDK">
    Le **SDK lomi.** est le moyen le plus rapide d'appeler l'API lomi. depuis le code de votre application, créer des sessions de checkout, gérer les clients et abonnements, émettre des remboursements et vérifier les webhooks, avec des méthodes typées et une gestion d'erreurs intégrée.

    Ce guide utilise le **SDK TypeScript** (`@lomi./sdk`). Le même parcours s'applique à [Python](/build/sdks/python), [Go](/build/sdks/go) et [PHP](/build/sdks/php). Installez avec `npm install @lomi./sdk`, définissez `LOMI_SECRET_KEY` dans `.env`, puis :

    ```typescript
    const session = await lomi.checkoutSessions.create({
      amount: 10000,
      currency_code: 'XOF',
      title: 'Abonnement premium',
      success_url: 'https://example.com/success',
      cancel_url: 'https://example.com/cancel',
    });

    console.log('Rediriger vers :', session.checkout_url);
    ```

    `lomi init` peut écrire automatiquement le client SDK, des fichiers d'exemple et votre `.env`. Parcours complet : [Démarrer avec le SDK](/start/sdk-quickstart). Références : [SDKs](/build/sdks).
  </IntegrationSurface>

  <IntegrationSurface transport="cli" title="Travailler depuis le terminal" identifier="lomi checkout create" href="/start/cli-quickstart" hrefLabel="Ouvrir le guide CLI">
    Le **CLI lomi.** est le moyen le plus rapide de s’authentifier, créer des checkouts de test, écouter les webhooks sans ngrok et installer des règles pour agents IA, depuis le terminal.

    Nécessite **Node.js 18+** (uniquement pour télécharger le binaire natif) :

    ```bash filename="Terminal"
    npm install -g lomi.cli
    lomi login
    lomi quickstart
    lomi checkout create \
      --amount 10000 \
      --currency XOF \
      --success-url https://example.com/success \
      --cancel-url https://example.com/cancel \
      --json
    ```

    Ouvrez le `checkout_url` de la réponse JSON. Relayer les webhooks avec `lomi listen http://localhost:3000/webhooks`. **`lomi login`** enregistre un jeton CLI. **`lomi init`** écrit votre clé API secrète (`LOMI_SECRET_KEY`) pour le SDK. Ce sont des identifiants distincts. Parcours complet : [Démarrer avec le CLI](/start/cli-quickstart). Référence : [CLI](/build/cli).
  </IntegrationSurface>

  <IntegrationSurface transport="mcp" title="Laisser un client IA appeler l’API marchande" identifier="lomi_checkout" href="/build/mcp" hrefLabel="Ouvrir le guide MCP">
    Le **Model Context Protocol (MCP)** laisse des assistants IA (Cursor, Claude Desktop, agents custom) appeler l’**API marchande lomi.** pour vous : créer des checkouts, lister les paiements, déboguer les webhooks, sans écrire chaque requête HTTP à la main.

    Recommandé pour Cursor / Claude / VS Code : ajoutez l’URL MCP hébergée **sans clé API**. Les clients OAuth ouvrent **Connect with lomi.** dans le navigateur :

    ```json
    {
      "mcpServers": {
      "lomi.": {
          "url": "https://mcp.lomi.africa/mcp"
        }
      }
    }
    ```

    Demandez ensuite au client de créer une session checkout (`lomi_checkout`, `action=create`). Les outils marchands suivent `lomi_<resource>` avec un `action` obligatoire. Dans le tableau de bord : **Paramètres → Intégrations → MCP**, puis **Développeurs → Clés API → Connect MCP**. Guide complet : [MCP pour clients IA](/build/mcp).
  </IntegrationSurface>
</IntegrationSurfaceGroup>

## Étape 1: Créer un compte développeur

Inscrivez-vous pour accéder à l’**environnement test** et exécuter des flux complets sans argent réel.

En mode test vous pouvez :

1. Accepter des paiements avec cartes test et mobile money simulé.
2. Créer sessions checkout, liens et charges directes sur l’API sandbox.
3. Recevoir des webhooks avec `"environment": "test"`.

Voir [Créer votre compte](/start/create-account) et [Clés API](/start/api-keys).

## Étape 2: Choisir votre intégration

lomi. propose plusieurs options d’intégration selon votre stack :

| Besoin                                       | Commencez par                                          |
| -------------------------------------------- | ------------------------------------------------------ |
| Page checkout complète                       | [Checkout hébergé](/build/accept/checkout)             |
| Checkout intégré sur votre site              | [Widget checkout](/build/accept/embed-widget)          |
| URL partageable                              | [Liens de paiement](/build/accept/payment-links)       |
| Demande de paiement créée côté backend       | [Demandes de paiement](/build/accept/payment-requests) |
| Mobile money ou cartes côté serveur          | [Charges directes](/build/accept/direct-charges)       |
| Facturation récurrente                       | [Abonnements](/build/billing/subscriptions)            |
| Plugin boutique (WooCommerce, Shopify, etc.) | [Extensions e‑commerce](/build/ecommerce-extensions)   |

Définissez ce que vous vendez dans [Produits](/build/billing/products) avant de créer des sessions checkout ou des plans d’abonnement.

La plupart des équipes commencent par le **checkout hébergé**. Consultez [Quelle intégration choisir ?](/build/choose-integration) et [Canaux de paiement](/build/payment-channels) pour confirmer la couverture Wave, MTN et cartes sur vos marchés.

## Étape 3: Tester de bout en bout

Testez votre intégration à fond avec les identifiants sandbox :

1. [Comment tester un paiement ?](/start/first-payment) : checkout CLI ou API.
2. [Paiements sandbox](/start/sandbox-payments): cartes, Wave, MTN
3. Tester les échecs avec [Simuler des erreurs](/build/reliability/simulate-errors)
4. [Gestion des erreurs](/build/reliability/error-handling) et [idempotence](/build/reliability/idempotency-keys)
5. Cas limites checkout (abonnements, essais, mobile money en attente) : [Comportement checkout](/build/accept/checkout-behavior) et guides par canal sous [Canaux de paiement](/build/payment-channels#channel-capabilities).

Le même premier checkout peut être créé depuis [REST](#call-api), le [SDK](#call-sdk), le [CLI](#call-cli) ou [MCP](#call-mcp). Les parcours CLI et cURL sont détaillés dans [Comment tester un paiement ?](/start/first-payment). SDK et MCP : [Démarrer avec le SDK](/start/sdk-quickstart) et [MCP](/build/mcp).

## Étape 4: Configurer les webhooks

Les webhooks sont essentiels pour les moyens de paiement et les événements hors de votre application, comme l’approbation mobile money et les renouvellements d’abonnement.

1. Enregistrez une URL HTTPS dans le [portail](https://lomi.africa/portal).
2. Suivez [Configurer les webhooks](/build/reliability) et [Traiter les webhooks](/build/reliability/handling-webhooks).
3. Vérifiez la signature sur le corps brut avant de parser le JSON.

**Renouvellements d’abonnement :** les abonnements carte se renouvellent hors session ; écoutez `SUBSCRIPTION_RENEWED` et les `PAYMENT_FAILED` de renouvellement. **Wave et MTN** utilisent un **lien checkout de renouvellement manuel** envoyé avant chaque échéance, le client doit payer ce lien ; pas de débit wallet silencieux. Voir [Abonnements : renouvellements](/build/billing/subscriptions#renewals-and-failed-payments).

## Étape 5: Passer en live

1. Vérification du compte et configuration des reversements.
2. Passez à `lomi_sk_live_...` et `https://api.lomi.africa`.
3. Suivez [Que vérifier avant le live ?](/start/go-live) et traitez un petit paiement live avec webhook.

<DocsNextSteps>
  <DocsNextStep href="/build/reliability/verify-payments" hint="Confirmer avant de livrer">
    Vérifier les paiements
  </DocsNextStep>

  <DocsNextStep href="/start/go-live" hint="Passer aux clés live">
    Passer en production
  </DocsNextStep>

  <DocsNextStep href="/build/accept/checkout" hint="Chemin de production">
    Checkout hébergé
  </DocsNextStep>

  <DocsNextStep href="/build/reliability" hint="Réconcilier côté serveur">
    Webhooks
  </DocsNextStep>
</DocsNextSteps>