Quickstart — Votre premier paiement en 5 minutes

Suivez ces 5 étapes pour encaisser votre premier paiement Orange Money CI en environnement sandbox.

Étape 1 — Créer un compte (1 min)

Rendez-vous sur dashboard.sandbox.nguepay.com/register et créez votre compte marchand gratuitement. Aucune carte bancaire n'est requise. Le mot de passe doit compter au moins 10 caractères, avec des lettres et des chiffres.

Étape 2 — Récupérer vos clés API (1 min)

Dans votre dashboard, section Clés API, copiez vos clés sandbox :

# Clés sandbox (pour tester)
pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx  # Clé publique
sk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx  # Clé secrète

Étape 3 — Initier un paiement (3 min)

curl -X POST https://api.sandbox.nguepay.com/api/v1/payments \
  -H "Authorization: Bearer sk_sandbox_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "orange",
    "amount": 5000,
    "currency": "XOF",
    "reference": "commande_001",
    "phone": "+2250700000000",
    "webhook_url": "https://votre-site.ci/webhook"
  }'

$response = Http::withToken('sk_sandbox_VOTRE_CLE')
  ->post('https://api.sandbox.nguepay.com/api/v1/payments', [
    'provider'  => 'orange',
    'amount'    => 5000,
    'currency'  => 'XOF',
    'reference' => 'commande_001',
    'phone'     => '+2250700000000',
  ]);

const r = await fetch('https://api.sandbox.nguepay.com/api/v1/payments', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_sandbox_VOTRE_CLE', 'Content-Type': 'application/json' },
  body: JSON.stringify({ provider: 'orange', amount: 5000, currency: 'XOF', reference: 'commande_001', phone: '+2250700000000' })
});

import requests
r = requests.post("https://api.sandbox.nguepay.com/api/v1/payments",
  headers={"Authorization": "Bearer sk_sandbox_VOTRE_CLE"},
  json={"provider": "orange", "amount": 5000, "currency": "XOF", "reference": "commande_001", "phone": "+2250700000000"})

Réponse :

{
  "success": true,
  "data": {
    "uuid":         "9d3f2b1a-7a10-4c2e-9f51-3b8d6e2c5678",
    "status":       "pending",
    "provider_code": "orange",
    "amount":       500000,
    "amount_xof":   5000,
    "currency":     "XOF",
    "checkout_url": "https://pay.sandbox.nguepay.com/pay/9d3f2b1a-7a10-4c2e-9f51-3b8d6e2c5678/simulate"
  }
}

Redirigez votre client vers checkout_url pour finaliser le paiement. En sandbox, c'est une page de simulation NguePay ; en live, c'est la page de l'opérateur (la page de paiement Orange Money, ou Stripe Checkout pour la carte). Pour une page NguePay qui propose tous les moyens activés, utilisez une session : POST /checkout/sessions.

Étape 4 — Recevoir la confirmation (webhook)

NguePay notifie chacune de vos destinations webhook dès que le paiement aboutit. Déclarez-les dans votre dashboard, onglet Webhooks : un compte peut en avoir jusqu'à cinq, chacune avec son propre secret de signature.

{
  "event": "payment.succeeded",
  "data": {
    "transaction_id": "9f1c0c2e-2b4a-4f0d-9a1b-6d2f7c3e4a55",
    "status":         "succeeded",
    "amount":         500000,
    "currency":       "XOF",
    "reference":      "commande_001",
    "provider":       "orange",
    "paid_at":        "2026-06-25T14:30:00Z"
  }
}

👉 Pensez à vérifier la signature avant tout traitement — c'est la seule chose qui distingue une vraie notification d'une requête fabriquée.

Étape 5 — Passer en production

• Complétez votre KYC dans le dashboard.
• Utilisez vos clés live : sk_live_xxx.
• Changez l'URL de base : https://api.live.nguepay.com/api/v1.