Comment utiliser les charges directes ?

Les charges directes permettent d’encaisser via POST /charge/* depuis votre serveur. Contrairement aux sessions checkout hébergées, vous construisez le parcours client.

Préférez le checkout hébergé ou les liens de paiement sauf si vous avez besoin de cartes embarquées ou d’un flux mobile money sur mesure. Les charges directes exigent la gestion des états en attente et des webhooks.

Quand utiliser les charges directes

Utilisez-les pour encaisser rapidement sans réutiliser un moyen de paiement enregistré, paiement ponctuel orchestré.

Rail	Endpoint	Étape client
Wave	`POST /charge/wave`	Ouvrir `wave_launch_url` ou `checkout_url`
MTN MoMo	`POST /charge/mtn`	Approuver sur le téléphone ; en live le statut démarre en `PENDING`
Carte	`POST /charge/card`	Confirmer avec `client_secret` via Payment Elements

Implémentation de référence

Exemple exécutable dans le monorepo :

Chemin : apps/plugins/direct-charge-integration-reference
Scripts cURL : curl/create-wave-charge.sh, curl/create-mtn-charge.sh

cd apps/plugins/direct-charge-integration-reference
pnpm install && cp .env.example .env
pnpm run dev

Flux carte (résumé)

POST /charge/card avec montant, devise et customer_id ou (customer_email + customer_name).
Monter Payment Elements avec lomi_pk_... et le client_secret retourné.
Écouter PAYMENT_SUCCEEDED pour la livraison.

Flux mobile money (résumé)

POST /charge/wave ou POST /charge/mtn avec montant, devise et téléphone E.164.
Rediriger ou guider le client selon la réponse.
Avant de livrer, confirmez le statut et le montant finaux via webhooks ou GET /transactions/{id}.

Voir Mobile money.

Scénarios bac à sable (clé test uniquement)

Avec une clé API test, les charges directes Wave et MTN se complètent automatiquement par défaut. Pour tester les chemins asynchrones ou les échecs en CI, envoyez X-Scenario-Key :

Valeur	Résultat
`pending`	La charge reste `PENDING` (pas d’auto-complétion)
`failed`	Erreur `400`

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/mtn" \
  -H "X-API-KEY: $LOMI_TEST_KEY" \
  -H "X-Scenario-Key: pending" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000,"currency":"XOF","customer_phone":"+2250700000000"}'

Le checkout hébergé et les charges carte directes ne prennent pas encore en charge cet en-tête. Voir Simuler les erreurs et Paiements en bac à sable.

lomi. Network

Les opérateurs peuvent créer des charges pour les comptes membres :

POST /charge/wave HTTP/1.1
X-API-KEY: lomi_sk_live_operator_...
Lomi-Account: acct_1234567890

Voir lomi. Network.