Dépôts & retraits

Un dépôt débite le compte mobile money d'un client et crédite votre wallet. Un retrait débite votre wallet et crédite le compte mobile money d'un bénéficiaire.

Les deux opérations sont asynchrones : l'API répond immédiatement 202 avec une transaction processing, puis vous notifie du résultat final par webhook.

Statut	Signification
processing	L'opération est transmise à l'opérateur, en attente de confirmation
completed	L'opération a abouti, le solde du wallet est mis à jour
failed	L'opération a échoué, aucun mouvement de fonds

Initier un dépôt

POST/api/v1/business/mobile-money/deposits

Paramètre	Type	Requis	Description
amount	string	Oui	Montant en centièmes de la devise ("10000" = 100 XAF), entier positif sans zéro initial. Multiple de 100 pour une devise sans décimales
currency_code	string	Oui	Code de devise ISO 4217 ; un wallet actif doit exister dans cette devise
phone_number	string	Oui	Numéro du payeur au format international, chiffres uniquement, sans + (8 à 15 chiffres)
provider	string	Oui	Code opérateur obtenu via Moyens de paiement
idempotency_key	string (UUID)	Oui	Identifiant unique de la tentative — voir Idempotence
pin	string	Oui	Quatre chiffres ; attendu par le format de la requête mais non vérifié pour un appel authentifié par clé API
country_code	string	Non	Code pays ISO 3166-1 alpha-3, par exemple COD

curl -X POST https://api.trustsend.africa/api/v1/business/mobile-money/deposits \
  -H "Authorization: Bearer $REEMITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50000",
    "currency_code": "CDF",
    "phone_number": "243813456789",
    "provider": "VODACOM_MPESA_COD",
    "idempotency_key": "7d6b1da7-654f-4760-915c-0a48e677316f",
    "pin": "0000"
  }'

Réponse 202

{
  "data": {
    "deposit_id": "TXN-VSWC4SQ2",
    "status": "processing",
    "created_at": "2026-09-12T10:00:00.000+00:00",
    "authorization": null
  }
}

authorization contient, lorsque l'opérateur l'exige, les instructions de validation à présenter au payeur (confirmation par code, étapes USSD, lien rapide). Il vaut null si aucune action particulière n'est nécessaire.

"authorization": {
  "pinPrompt": "MANUAL",
  "pinPromptRevivable": false,
  "channels": [
    {
      "type": "USSD",
      "displayName": { "fr": "Code USSD" },
      "quickLink": null,
      "steps": { "fr": ["Composez *150#", "Choisissez « Paiements en attente »", "Confirmez avec votre code secret"] }
    }
  ]
}

Erreurs

Code	Cause
403	Fonctionnalité mobile_money.deposits non incluse dans votre offre
404	Aucun wallet actif dans la devise demandée — créez-en un
409	idempotency_key déjà utilisée avec un contenu de requête différent
422	Devise ou opérateur non pris en charge, ou montant en dehors des bornes de l'opérateur
503	Réseau de paiement temporairement indisponible — réessayez avec la même idempotency_key

Initier un retrait

POST/api/v1/business/mobile-money/payouts

Les paramètres sont identiques à ceux du dépôt ; phone_number désigne le numéro du bénéficiaire.

Réponse 202

{
  "data": {
    "payout_id": "TXN-K2P9QD7M",
    "status": "processing",
    "created_at": "2026-09-12T10:05:00.000+00:00"
  }
}

Erreurs — en plus de celles du dépôt :

Code	Cause
400	Plafond de transaction du wallet dépassé
402	Solde du wallet insuffisant

Consulter une opération

GET/api/v1/business/mobile-money/deposits/:id

GET/api/v1/business/mobile-money/payouts/:id

Renvoie le statut enregistré par Reemite.

Réponse 200

{
  "data": {
    "deposit_id": "TXN-VSWC4SQ2",
    "status": "completed",
    "created_at": "2026-09-12T10:00:00.000+00:00",
    "completed_at": "2026-09-12T10:00:42.000+00:00"
  }
}

Erreurs : 403 si l'opération appartient à un autre compte, 404 si elle est introuvable.

Vérifier le statut en temps réel

GET/api/v1/business/mobile-money/deposits/:id/live-status

GET/api/v1/business/mobile-money/payouts/:id/live-status

Interroge le réseau de paiement à l'instant de l'appel. Lorsqu'un statut final est obtenu, la transaction est mise à jour immédiatement. L'appel est idempotent : il ne crédite ni ne débite jamais deux fois.

À utiliser lorsqu'une opération reste processing plus longtemps que prévu, par exemple si un webhook n'a pas été reçu.

Réponse 200

{
  "data": {
    "deposit_id": "TXN-VSWC4SQ2",
    "local_status": "completed",
    "live_status": "COMPLETED",
    "provider_transaction_id": "8f3c2a91-4b7e-4d2a-9c61-0e5d7b1a2f44",
    "failure_reason": null
  }
}

Champ	Description
local_status	Statut enregistré par Reemite après la vérification
live_status	Statut remonté en temps réel par le réseau de paiement
provider_transaction_id	Référence de l'opération côté opérateur, utile en cas de réclamation
failure_reason	Motif de l'échec, null si l'opération n'a pas échoué

Erreurs : 503 si le réseau de paiement est indisponible ou n'a pas encore enregistré l'opération.

astuce

Appuyez-vous en priorité sur les webhooks pour connaître le résultat d'une opération. Réservez cet endpoint aux vérifications ponctuelles plutôt qu'à une interrogation en boucle.