Comment bloquer une caution carte ?

Un blocage carte réserve un montant sur la carte du client sans le prélever. Vous capturez ce que vous gardez, et le reste est libéré. Utilisez-le pour une caution de location, ou tout encaissement dont le montant final n’est pas encore connu.

Le blocage est un encaissement carte à part. Le reste de la vente, par exemple le loyer, peut rester chez un autre acquéreur carte. Le client saisit la carte de caution avec lomi. Elements. Il n’y a pas de terminal physique.

Cartes, durée et frais

Visa et Mastercard peuvent être bloquées. Certaines cartes de débit refusent le blocage, ou débitent tout de suite. Les cartes de crédit et les cartes internationales sont le cas fiable.

Un blocage en ligne classique dure 7 jours après la confirmation de la carte. Quand le réseau de la carte autorise un blocage plus long, il peut durer jusqu’à 30 jours (29 jours et 18 heures sur Visa). capture_before sur GET /charge/card/{id} est la date limite. La banque du client peut lever le blocage plus tôt.

Chaque blocage coûte 1 000 F CFA (2 USD ou 2 EUR). Ces frais sont dus que vous libériez la caution ou que vous en préleviez une partie. Un prélèvement ajoute aussi le tarif carte habituel, uniquement sur le montant prélevé. Ce montant doit être d’au moins 1 000 F CFA (0,50 EUR ou USD). Un seul prélèvement est possible. Un montant inférieur libère le reste. Si le montant prélevé ne couvre pas les frais de caution et le tarif carte, le prélèvement est refusé et le blocage reste en place.

Ces frais apparaissent dans Autres frais (Réglages → Frais), pas sur la ligne du tarif carte. Sur la transaction, Détails du paiement indique Caution carte et l’heure de fin du blocage.

Bloquer, prélever ou libérer

1. POST /charge/card avec hold à true, plus le montant, la devise, et customer_id ou (customer_email et customer_name). Envoyez Idempotency-Key.
2. Confirmez la carte avec lomi. Elements et le client_secret reçu.
3. GET /charge/card/{id} jusqu’à ce que status vaille requires_capture. amount_capturable est le montant encore bloqué, dans votre devise. can_increment vaut vrai quand cette carte peut accepter un blocage plus élevé.
4. POST /charge/card/{id}/increment avec le nouveau total, dans la même devise, avant le prélèvement. Envoyez Idempotency-Key. Le nouveau total doit être supérieur au blocage actuel. Certaines cartes ne peuvent pas être augmentées. Quand can_increment vaut faux, prélevez ou libérez le blocage actuel. Un refus laisse ce blocage en place.
5. POST /charge/card/{id}/capture pour prélever. Omettez amount pour tout le blocage, ou envoyez un montant inférieur dans la même devise. Envoyez Idempotency-Key.
6. POST /charge/card/{id}/cancel pour libérer le blocage sans rien prélever.

La vente reste en attente jusqu’à l’enregistrement du prélèvement, puis elle passe à completed. Une libération ou un blocage expiré ne crédite pas votre solde.

Sur le tableau de bord, une caution en attente affiche Prélever, Augmenter et Libérer. Ces actions font le même prélèvement, la même augmentation et la même annulation que l’API.

Un agent peut passer par MCP lomi_card_holds (create, get, increment, capture, cancel) ou par le CLI (lomi charges hold, get, raise, capture, release).

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/card" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Idempotency-Key: hold-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount":100000,"currency_code":"XOF","hold":true,"customer_email":"client@example.com","customer_name":"Awa Ndiaye","description":"Caution véhicule"}'

curl -sS "https://sandbox.api.lomi.africa/charge/card/pi_123" \
  -H "X-API-KEY: $LOMI_SECRET_KEY"

{
  "success": true,
  "data": {
    "id": "pi_123",
    "status": "requires_capture",
    "hold": true,
    "can_increment": true,
    "original_amount": 100000,
    "original_currency": "XOF",
    "amount_capturable": 100000,
    "capture_before": "2026-10-07T12:00:00.000Z"
  }
}

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/card/pi_123/increment" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Idempotency-Key: raise-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount":150000}'

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/card/pi_123/capture" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Idempotency-Key: capture-1001" \
  -H "Content-Type: application/json" \
  -d '{"amount":25000}'

curl -sS -X POST "https://sandbox.api.lomi.africa/charge/card/pi_123/cancel" \
  -H "X-API-KEY: $LOMI_SECRET_KEY"