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.

Les charges directes carte et Switch ne sont pas encore disponibles. POST /charge/card et POST /charge/switch sont désactivés le temps de finaliser les rails carte, et les appeler aujourd’hui renvoie 503 service_unavailable. Utilisez le checkout hébergé ou les liens de paiement pour les cartes. Seules les charges directes mobile money Wave et MTN sont actives.

Préférez le checkout hébergé ou les liens de paiement sauf si vous avez besoin 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`	Pas encore disponible: utilisez le checkout hébergé
Switch (carte côté serveur)	`POST /charge/switch`	Pas encore disponible: utilisez le checkout hébergé

Implémentation de référence

Exemple exécutable dans le monorepo :

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

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

Flux carte (résumé)

Pas encore disponible. Les étapes ci-dessous décrivent le flux carte prévu ; POST /charge/card et POST /charge/switch renvoient actuellement 503 service_unavailable. Utilisez le checkout hébergé pour les cartes.

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.