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	Requis	Code ISO 4217 — actuellement `XOF`
`method`	string	Requis	Opérateur : `orange` · `mtn` · `moov` · `wave` · `djamo`
`country`	string	Requis	Code ISO alpha-2 : `CI` · `SN` · `BF` · `TG` · `ML`
`phone`	string	Requis	Numéro du payeur au format E.164 : `+2250701234567`
`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	Provider utilisé : `jeko` · `julaya` · `intouch`
`provider_ref`	string	Référence côté provider (pour réconciliation)
`requires_action`	boolean	`true` si une redirection est nécessaire
`action_url`	string\|null	URL de redirection Mobile Money (Wave, Orange…)
`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": "+2250701234567",
    "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": "+2250502345678",
    "reference": "order_2024_002"
  }'

json Réponse Wave (redirect)

{
  "success": true,
  "status": "initiated",
  "transaction_id": "PAY_ABCDEF123456_1719100000",
  "provider": "jeko",
  "provider_ref": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
  "requires_action": true,
  "action_url": "https://pay.jeko.africa/payment/d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
  "message": "Redirect to payment page required."
}

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 ($data['requires_action']) {
    return redirect($data['action_url']);
}

Statuts de transaction

Statut	Signification	Action
initiated	Transaction créée, en attente du client	Rediriger vers `action_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