# Shopify
Source: https://docs.lomi.africa/build/ecommerce-extensions/shopify

Installer l’app lomi. Shopify (installation personnalisée), activer le paiement panier et accepter mobile money et cartes via sessions checkout et webhooks signés.

***

title: Shopify
description:
Installer l’app lomi. Shopify (installation personnalisée), activer le paiement
panier et accepter mobile money et cartes via sessions checkout et webhooks signés.
-----------------------------------------------------------------------------------

import { Callout } from '@/components/docs/docs-callout';

# Shopify

L’app lomi. pour Shopify permet aux marchands d’accepter **Wave, mobile money, cartes et plus** depuis la **page panier** via le checkout hébergé lomi. Les commandes Shopify sont créées en **brouillon avant la redirection** et finalisées au succès du paiement.

<Callout type="info">
  Il s’agit d’une intégration **contournement panier**, distribuée en **installation personnalisée**. Ce n’est pas un moyen de paiement natif au checkout Shopify et ce n’est pas une app de paiement sur l’App Store.
</Callout>

<Callout type="info" title="Produits associés">
  * **Clés API** : [Tableau de bord → Développeurs → Clés API](/start/api-keys)
  * **Webhooks** : [Webhooks du tableau de bord](/build/reliability) — abonnez-vous à **`PAYMENT_SUCCEEDED`** et **`REFUND_COMPLETED`**
  * **Checkout hébergé** : [Checkout](/build/accept/checkout), où le client paie après redirection
  * **Intégrations** : [Tableau de bord → Canaux de paiement → Intégrations](https://dashboard.lomi.africa) pour l’installation OAuth
</Callout>

## Prérequis

* Boutique Shopify avec l’app lomi. installée (lien d’installation personnalisé)
* Compte marchand lomi. avec **clé secrète API** et **secret de signature webhook**
* Devise boutique prise en charge par lomi. (ex. **XOF**, **USD**, **EUR**)

Distribution en **installation personnalisée** depuis le [tableau de bord lomi.](https://dashboard.lomi.africa) (pas de release publique sur GitHub).

## Étape 1, Installer l’app

1. [dashboard.lomi.africa](https://dashboard.lomi.africa) → **Paramètres → Canaux de paiement → Intégrations**.
2. Activez **Shopify**, saisissez votre domaine, puis **Installer sur Shopify**.

URL : `https://connect.lomi.africa/install?shop={boutique}.myshopify.com`

## Étape 2, Connecter les clés API

Dans l’app → **Settings**, collez la **clé secrète de test** et le **secret webhook de test**, puis connectez.

L’app choisit le bac à sable ou la production selon le préfixe de la clé.

## Étape 3, Vérifier Setup health

Le panneau **Setup health** doit afficher la clé configurée, `GET /me` réussi et le mode test (bac à sable).

## Étape 4, Connecter les webhooks

Créez l’endpoint dans le tableau de bord avec l’URL affichée dans Settings. Activez **`PAYMENT_SUCCEEDED`** et **`REFUND_COMPLETED`**.

## Étape 5, Ajouter le bloc panier

**Boutique en ligne → Thèmes → Personnaliser → Panier** → bloc **Pay with lomi.**

## Étape 6, Faire un paiement test

Payez depuis le panier sur le checkout hébergé et vérifiez la finalisation du brouillon Shopify.

## Récapitulatif de configuration

1. Collez la **clé secrète** et le **secret webhook** dans les réglages de l’app.
2. Dans [dashboard.lomi.africa](https://dashboard.lomi.africa) → **Webhooks**, créez un endpoint :
   * URL : `{hôte_app}/api/webhooks/lomi/payment-success`
   * Événement : **`PAYMENT_SUCCEEDED`**
3. Choisissez le **mode de livraison** : sous-total seul ou sous-total + **frais de port fixes**.
4. Dans **Boutique en ligne → Thèmes → Personnaliser → Panier**, ajoutez le bloc **Pay with lomi.** et enregistrez.
5. Testez avec un panier contenant plusieurs articles.

## Flux de paiement

1. Le client clique **Payer avec lomi.** sur le panier.
2. Le bloc lit `/cart.js` et appelle **`POST /apps/lomi/cart-pay`** (proxy d’app signé).
3. L’app crée un **brouillon de commande** Shopify avec toutes les lignes.
4. L’app crée une **session checkout** lomi. (montant = total du brouillon).
5. Paiement sur lomi. → webhook **`PAYMENT_SUCCEEDED`** → finalisation du brouillon.
6. Page **`/shopify/order-complete`** : panier vidé, référence commande affichée.

## Webhooks

| En-tête            | Rôle                                                                          |
| ------------------ | ----------------------------------------------------------------------------- |
| `X-Lomi-Event`     | Doit être `PAYMENT_SUCCEEDED` pour finaliser le brouillon                     |
| `X-Lomi-Signature` | HMAC-SHA256 hex du **corps brut**, secret = secret webhook du tableau de bord |

Métadonnées utilisées pour la réconciliation :

* `shopify_shop`
* `shopify_draft_order_id`
* `shopify_draft_order_name`
* `shopify_checkout_session_id`

## Limitations

* Pas de **partenaire paiements** / moyen de paiement natif au checkout (pas Shop Pay, pas de passerelle UI checkout).
* **Livraison et taxes** du checkout Shopify indisponibles sur la page panier : sous-total seul ou **forfait de livraison fixe** dans les réglages de l’app.
* **Remboursements** gérés dans le tableau de bord lomi., pas automatiquement depuis l’admin Shopify.
* Ne **soumettez pas** ce flux contournement panier à l’App Store public Shopify (politique Shopify sur le contournement du checkout).

## QA mise en production

| Scénario                 | Attendu                                                     |
| ------------------------ | ----------------------------------------------------------- |
| Panier un article        | Une ligne sur le brouillon ; montant lomi = total brouillon |
| Multi-articles / qté > 1 | Toutes les variantes et quantités sur le brouillon          |
| Mode sous-total seul     | Pas de ligne livraison sur le brouillon                     |
| Mode forfait livraison   | Total brouillon = sous-total + frais configurés             |
| Paiement réussi          | Brouillon finalisé ; panier vidé sur la page succès         |
| Relance webhook          | Pas de commandes Shopify en double                          |
| Annulation sur lomi.     | Client revient sur `/cart` ; brouillon reste ouvert         |

## Voir aussi

* [Hub extensions e‑commerce](/build/ecommerce-extensions)
* [WooCommerce](/build/ecommerce-extensions/woocommerce) : référence pour checkout hébergé + contrat webhook
* [Webhooks](/build/reliability)