# Comment utiliser les charges ?
Source: https://docs.lomi.africa/build/accept/direct-charges
Encaissements initiés côté serveur pour une application qui doit verrouiller un seul rail. Le checkout hébergé est le choix par défaut.
***
title: 'Comment utiliser les charges ?'
description: 'Encaissements initiés côté serveur pour une application qui doit verrouiller un seul rail. Le checkout hébergé est le choix par défaut.'
------------------------------------------------------------------------------------------------------------------------------------------------------
import { Callout } from '@/components/docs/docs-callout';
Les charges directes sont pour une application qui doit verrouiller un seul rail. Le checkout hébergé est le choix par défaut : créez une [session de checkout](/build/accept/checkout), le client choisit le moyen, et un nouveau rail apparaît sans changer votre code. `POST /charge/*` encaisse depuis votre serveur et vous construisez le parcours client.
Les charges Switch (`POST /charge/switch`) ne sont pas disponibles. Elles renvoient `503 service_unavailable`. Utilisez le [checkout hébergé](/build/accept/checkout) ou [lomi. Elements](/build/accept/payment-elements) pour les cartes.
Préférez le [checkout hébergé](/build/accept/checkout) ou les [liens de paiement](/build/accept/payment-links) 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 | `POST /charge/mtn` | Approuver sur le téléphone ; en live le statut démarre en `PENDING` |
| Carte | `POST /charge/card` | Monter [lomi. Elements](/build/accept/payment-elements) avec le `client_secret` |
| Switch (carte côté serveur) | `POST /charge/switch` | **Pas disponible**: utilisez le [checkout hébergé](/build/accept/checkout) |
## 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`
```bash
cd apps/plugins/references/direct-charge-integration-reference
pnpm install && cp .env.example .env
pnpm run dev
```
## Flux carte (résumé)
1. `POST /charge/card` avec montant, devise et `customer_id` ou (`customer_email` + `customer_name`).
2. Monter [lomi. Elements](/build/accept/payment-elements) avec `lomi_pk_test_…` ou `lomi_pk_live_…` et le `client_secret` retourné.
3. Écouter `PAYMENT_SUCCEEDED` pour la livraison.
Le montant carte minimum est 1 000 F CFA (0,50 EUR/USD). Le numéro de carte n’atteint jamais votre serveur ni l’API lomi.
## Flux mobile money (résumé)
1. `POST /charge/wave` ou `POST /charge/mtn` avec montant, devise et téléphone E.164.
2. Rediriger ou guider le client selon la réponse.
3. Avant de livrer, confirmez le **statut** et le **montant** finaux via webhooks ou `GET /transactions/{id}`.
Voir [Mobile money](/build/mobile-money).
### Champs de requête Wave
`POST /charge/wave`
| Champ | Type | Obligatoire | Description |
| ---------------------- | -------- | ----------- | --------------------------------------- |
| `amount` | `number` | Oui | Montant (minimum 100). |
| `currency` | `string` | Oui | Doit être `XOF`. |
| `customer` | `object` | Oui | Détails client. |
| `customer.name` | `string` | Oui | Nom complet. |
| `customer.email` | `string` | Non | E-mail. |
| `customer.phoneNumber` | `string` | Non | Téléphone E.164 (ex. `+2250102030405`). |
| `description` | `string` | Non | Description. |
| `successUrl` | `string` | Non | Redirection après succès. |
| `errorUrl` | `string` | Non | Redirection après échec. |
| `environment` | `string` | Non | `live` ou `test` (défaut `live`). |
Une réponse `201` inclut `transactionId`, `checkoutUrl` et la session Wave. `POST /charge/mtn` suit le même schéma.
Les endpoints carte (`POST /charge/card`, `GET /charge/card/{id}`, `POST /charge/card/{id}/increment`, `POST /charge/card/{id}/capture`, `POST /charge/card/{id}/cancel`) sont dans la référence REST. Pour bloquer une caution sans la prélever, mettez `hold` à `true` et suivez [Blocages carte](/build/accept/card-holds). Switch (`POST /charge/switch`) renvoie encore `503 service_unavailable`.
## 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` |
```bash
curl -sS -X POST "https://sandbox.api.lomi.africa/charge/mtn" \
-H "X-API-KEY: $LOMI_SECRET_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](/build/reliability/simulate-errors) et [Paiements en bac à sable](/start/sandbox-payments#testing-mobile-money).
## lomi. Network
Les opérateurs peuvent créer des charges pour les comptes membres :
```http
POST /charge/wave HTTP/1.1
X-API-KEY: lomi_sk_live_operator_...
Lomi-Account: acct_1234567890
```
Voir [lomi. Network](/build/platform/network).
## Dépannage
Utilisez `GET /providers` pour confirmer quels rails sont connectés pour l’organisation avant d’appeler les endpoints de charge directe.
| Symptôme | Cause probable | Correctif |
| ------------------------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Charge carte `503 service_unavailable` | Les charges carte directes ne sont pas configurées sur le déploiement API | **Ops :** les identifiants plateforme carte doivent être définis sur le service API pour l’environnement cible. **Les marchands ne configurent pas de clés processeur carte** : les charges carte directes tournent sur l’infrastructure lomi. |
| Charge Wave `400` sur Aggregated Merchant ID manquant | Wave n’est pas entièrement connecté dans le tableau de bord | Connectez Wave dans le tableau de bord et enregistrez l’**Aggregated Merchant ID** de l’organisation. |
| Charge Wave `400` avec une erreur Wave | Payload invalide ou rejet côté Wave | Envoyez `currency: "XOF"`, `customer.phoneNumber` imbriqué en E.164, et optionnellement `successUrl` / `errorUrl` (camelCase). Voir [Wave](/build/payment-methods/wave). |
| Charge carte `400` sur les champs client | Champs de rapprochement manquants | Incluez `customer_id`, ou à la fois `customer_email` et `customer_name`. |
| Le checkout hébergé fonctionne mais la charge directe échoue | Prérequis différents selon le rail | Le checkout hébergé utilise l’app checkout lomi. ; les charges directes appellent `/charge/*` et exigent la forme de payload et la connexion prestataire. |
Les marchands n’ont besoin que de `lomi_sk_...` (serveur) et `lomi_pk_...` (Payment Elements). Ils ne configurent jamais eux-mêmes les secrets plateforme de paiement carte.
## Voir aussi
* [Créer une charge Wave](/api/charge/ChargesController_createWaveCharge)
* [Créer une charge MTN](/api/charge/ChargesController_createMtnCharge)
* [Créer une charge carte](/api/charge/ChargesController_createCardCharge)
* [Traiter les webhooks](/build/reliability/handling-webhooks)