Payin API

Collectez des paiements depuis les wallets Mobile Money de vos clients via un seul endpoint.

Endpoint Paramètres Réponse Opérateurs Exemples Statuts

Endpoint

POST /api/v1/merchant/payin Scope requis : payin

Paramètres

Champ	Type	Requis	Description
`amount`	integer	Requis	Montant en XOF (min API : 100, max : 10 000 000). Certains services imposent un minimum supérieur, notamment 200 XOF pour T-Money Togo.
`currency`	string	Optionnel	Code ISO 4217 — défaut `XOF`
`method`	string	Requis	Opérateur : `orange` · `mtn` · `moov` · `wave` · `tmoney` · `yas` · `mobile_money`
`country`	string	Requis	Code ISO alpha-2 du pays du payeur : `CI` · `SN` · `BF` · `TG` · `ML` · `BJ` · `GN`. Détermine les frais applicables.
`phone`	string	Requis	Numéro du payeur au format local ou international : `0701234567`, `22893752340` ou `+22893752340`. Pour le Togo, le numéro local comporte 8 chiffres sans zéro initial.
`reference`	string	Requis	Référence unique côté marchand (max 100 chars)
`description`	string	Optionnel	Description affichée au client (max 255 chars)
`otp`	string	Conditionnel	Code OTP généré par le client dans son app opérateur. Recommandé pour `orange` — certains providers (Hyperfast) l’exigent. Accepté aussi via `metadata.otp`.
`customer_name`	string	Optionnel	Nom du client
`customer_email`	string	Optionnel	Email du client
`metadata`	object	Optionnel	Données libres retournées dans les webhooks

Header Idempotency-Key obligatoire

Chaque requête payin doit inclure un header Idempotency-Key unique. Utilisez votre reference comme valeur. Voir Idempotency.

OTP Orange Money

Pour method=orange, demandez au client de générer un code OTP dans son application Orange Money (menu paiement marchand) ou via #144#, puis envoyez-le dans le champ otp (ou metadata.otp). Sans OTP, le système choisit automatiquement un provider qui n’en a pas besoin (lien de paiement redirect) — ou la page payment_url collecte elle-même le code auprès du client quand c’est nécessaire. Vous n’avez rien à gérer.

Orange Money — two ways, your choice (no code change required)

Send nothing — it works as before: your customer either gets a payment link or types their Orange Money OTP on our hosted checkout page. No code change needed on your side.
Send otp — faster direct payment: the customer generates the OTP in their Orange Money app (or via #144#) and the payment is confirmed instantly, without any link.

Frais par pays

Le champ country détermine les frais de transaction appliqués. Votre clé API peut avoir des taux différents selon le pays. Contactez l'équipe commerciale pour configurer vos taux par pays.

Réponse

Champ	Type	Description
`success`	boolean	Toujours `true` si HTTP 200
`status`	string	`initiated` · `pending` · `timeout_review` · `success` · `failed`
`transaction_id`	string	ID interne EnvoiFacile (à conserver)
`provider`	string	Toujours `envoifacile`
`payment_url`	string\|null	Lien de paiement hébergé par EnvoiFacile — redirigez votre client ici
`message`	string	Message lisible
`data.confirmation_type`	string\|null	`redirect` (lien opérateur) · `operator_push` (confirmation PIN sur le téléphone) · `sms_ussd` (le client reçoit un SMS et compose le code USSD pour valider) · `otp` (code OTP collecté sur la page checkout)

Exemples

Orange Money CI

bash curl

curl -X POST https://envoifacile.com/api/v1/merchant/payin \
  -H "X-API-KEY: ef_live_xxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order_2024_001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "method": "orange",
    "country": "CI",
    "phone": "0701234567",
    "reference": "order_2024_001",
    "otp": "123456",
    "description": "Paiement commande #001"
  }'

Wave CI

bash curl

curl -X POST https://envoifacile.com/api/v1/merchant/payin \
  -H "X-API-KEY: ef_live_xxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order_2024_002" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XOF",
    "method": "wave",
    "country": "CI",
    "phone": "0502345678",
    "reference": "order_2024_002"
  }'

T-Money Togo

bash curl

curl -X POST https://envoifacile.com/api/v1/merchant/payin \
  -H "X-API-KEY: ef_live_xxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order_tg_001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200,
    "currency": "XOF",
    "method": "tmoney",
    "country": "TG",
    "phone": "+22893752340",
    "reference": "order_tg_001",
    "description": "Paiement T-Money Togo"
  }'

Routage Togo

Utilisez country=TG avec method=tmoney pour T-Money/Yas, ou method=moov pour Moov/Flooz. EnvoiFacile sélectionne automatiquement le provider ; votre intégration ne doit pas envoyer de nom de provider.

json Réponse (initiated, redirect requis)

{
  "success": true,
  "status": "initiated",
  "transaction_id": "PAY_ABCDEF123456_1719100000",
  "provider": "envoifacile",
  "message": "Redirect to payment page required.",
  "payment_url": "https://envoifacile.com/checkout/PAY_ABCDEF123456_1719100000",
  "data": {
    "requires_action": true,
    "provider_ref": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc"
  }
}

Utilisez payment_url

Redirigez votre client vers payment_url. Cette page hébergée par EnvoiFacile gère tout : redirection opérateur (Orange, Wave…), saisie du code OTP Orange Money si requis, confirmation push MTN/Moov, puis affiche le statut final. Vous n’avez pas besoin de gérer les URLs brutes des opérateurs ni l’OTP.

Exemple PHP (Laravel)

php Laravel HTTP Client

$response = Http::withHeaders([
    'X-API-KEY'        => env('ENVOIFACILE_API_KEY'),
    'Idempotency-Key'  => 'order_' . $order->id,
    'Content-Type'     => 'application/json',
])->post('https://envoifacile.com/api/v1/merchant/payin', [
    'amount'    => 5000,
    'currency'  => 'XOF',
    'method'    => 'orange',
    'country'   => 'CI',
    'phone'     => $customer->phone,
    'reference' => 'order_' . $order->id,
]);

$data = $response->json();

if (!empty($data['payment_url'])) {
    return redirect($data['payment_url']);
}

Statuts de transaction

Statut	Signification	Action
initiated	Transaction créée, en attente du client	Rediriger vers `payment_url`
pending	En cours de traitement chez l'opérateur	Attendre le webhook
timeout_review	Résultat provider ambigu ou confirmation tardive	Ne pas relancer ; attendre la réconciliation ou contacter le support
success	Paiement confirmé et fonds reçus	Valider la commande
failed	Échec explicite et confirmé par le provider	Une nouvelle tentative peut être proposée avec une nouvelle référence