Premier payin sandbox

Un payin encaisse de l'argent depuis le téléphone d'un client. En sandbox, le résultat est déterministe. Il dépend des 3 derniers chiffres du numéro de téléphone.

1. Créer le payin

Appelez POST /v1/payins. Le montant est en unités mineures (une chaîne de chiffres). Le merchantReference est votre référence métier. FreeGate en dérive la clé d'idempotence.

Cinq champs sont requis : countryIso2, operatorCode, amountMinor, customerPhone, merchantReference. Les URLs de retour (successUrl, failedUrl, cancelUrl, returnUrl) et metadata sont optionnels : les URLs redirigent le client depuis la page de paiement hébergée et remplacent les valeurs par défaut de votre application.

curl -X POST "$BASE_URL/v1/payins" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "countryIso2": "CI",
    "operatorCode": "DJAMO",
    "amountMinor": "25000",
    "customerPhone": "+2250100000001",
    "merchantReference": "school-fees-001",
    "successUrl": "https://votre-site.com/paiement/succes",
    "failedUrl": "https://votre-site.com/paiement/echec",
    "cancelUrl": "https://votre-site.com/paiement/annule",
    "returnUrl": "https://votre-site.com/paiement/retour",
    "metadata": { "orderId": "cmd_123" }
  }'

La réponse contient l'identifiant de transaction, un status public et un objet nextAction :

{
  "data": {
    "transactionId": "txn_payin_...",
    "status": "PENDING",
    "amount": "250.00",
    "currency": "XOF",
    "checkoutUrl": null,
    "nextAction": { "type": "NONE", "url": null }
  },
  "meta": { "environment": "SANDBOX", "type": "payin" }
}

2. Traiter nextAction

Selon l'opérateur, une action peut être requise. Voici le résumé.

Chaque type est détaillé, avec des exemples, dans Traiter nextAction.

3. Suivre le résultat

Le paiement se termine de façon asynchrone. Vous avez deux moyens.

• Webhook : FreeGate envoie un événement signé payment.payin.succeeded ou payment.payin.failed. Voir Webhooks.
• Polling : GET /v1/transactions/{transactionId} renvoie le statut courant.

Scénarios sandbox

En sandbox, le résultat dépend du suffixe (3 derniers chiffres) du numéro, quel que soit le pays ou l'opérateur.