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 : 100, max : 10 000 000)
`currency`	string	Optionnel	Code ISO 4217 — défaut `XOF`
`method`	string	Requis	Opérateur : `orange` · `mtn` · `moov` · `wave` · `mobile_money`
`country`	string	Optionnel	Code ISO alpha-2 : `CI` · `SN` · `BF` · `TG` · `ML` (défaut : `CI`)
`phone`	string	Requis	Numéro du payeur au format local : `0701234567` (sans indicatif pays)
`reference`	string	Requis	Référence unique côté marchand (max 100 chars)
`description`	string	Optionnel	Description affichée au client (max 255 chars)
`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.

Réponse

Champ	Type	Description
`success`	boolean	Toujours `true` si HTTP 200
`status`	string	`initiated` · `pending` · `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

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",
    "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"
  }'

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 redirige automatiquement vers l’opérateur (Orange, Wave, MTN…) puis affiche le statut final. Vous n’avez pas besoin de gérer les URLs brutes des opérateurs.

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
success	Paiement confirmé et fonds reçus	Valider la commande
failed	Paiement refusé ou timeout	Proposer une nouvelle tentative