Démarrer

SandBox (tests)

Testez toute votre intégration sans téléphone ni argent réel, avant même la vérification de votre compte. C’est la clé API qui choisit l’environnement.

Deux clés, deux environnements

Clé	Environnement	Opérations
`pk_test_…`	`SANDBOX`	Simulées : aucun téléphone sollicité, portefeuille de test au solde fictif
`pk_live_…`	`LIVE`	Réelles : vrais téléphones, vrai argent

Mêmes routes, même adresse, même secret webhook et même URL de webhook : pour passer en production, il suffit de remplacer la clé. Les données sont séparées : une clé de test ne voit jamais une opération réelle, et inversement.

Moment	Clé de test	Clé de production
Création d’un service, compte non vérifié	Affichée une fois	Aucune
Validation de votre compte par Nebryon	—	Générée : à afficher une seule fois depuis l’espace (Intégration)
Création d’un service, compte déjà vérifié	Affichée une fois	Affichée une fois

Un service créé avant l’arrivée de la SandBox n’a pas encore de clé de test : générez-la depuis votre espace (Intégration › Clé de test › Générer).

Ce qui change en test

	Production	SandBox
Compte partenaire	Doit être vérifié	Pas nécessaire
Portefeuille	Réel, ouvert à 0	1 000 000 XOF fictifs à la première utilisation
Opérateur désactivé	`503 OPERATOR_DISABLED`	Ignoré
`collectionNumber`	Numéro d’une SIM collectrice	`+22600000000`
Exécution	Téléphones	Simulée (scénarios ci-dessous)
`externalReference`	Unique par service	Unique par service et environnement : vous pouvez réutiliser en test une référence de production
Frais, montants min/max, doublons, solde insuffisant	Appliqués	Appliqués à l’identique

Paiement de test

curl -X POST "https://paygate.nebyron.com/management/gatewaytransaction/api/payment" \
  -H "X-API-Key: $NEBRYON_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "phoneNumber": "70120000",
    "network": "ORANGE_MONEY",
    "externalReference": "TEST-CMD-1042"
  }'

Reconnaître une opération de test

Chaque transaction porte environment (SANDBOX ou LIVE) et livemode (false en test).
Chaque réponse de l’API porte l’en-tête X-Gateway-Environment de la clé utilisée.
La référence opérateur d’une opération simulée commence par SBX.

Réponse

HTTP/1.1 200
X-Gateway-Environment: SANDBOX

{
  "reference": "PAY261005R1A3NKNJGZ",
  "externalReference": "TEST-CMD-1042",
  "type": "PAYMENT",
  "status": "PENDING",
  "amount": 5000.0,
  "fee": 75.0,
  "collectionNumber": "+22600000000",
  "environment": "SANDBOX",
  "livemode": false,
  "...": "…"
}

Scénarios simulés

Le résultat dépend des 4 derniers chiffres du numéro de téléphone :

Opération	Numéro finissant par	Résultat
Paiement	`0000`	`SUCCESS` après ~3 s (`payment.succeeded`), portefeuille de test crédité
Paiement	`0001`	`EXPIRED` après ~3 s (`payment.expired`)
Paiement	autre	Reste `PENDING` : à déclencher (ci-dessous), sinon expire au bout de 15 min
Retrait	`0001`	`PROCESSING` puis `FAILED` (`withdrawal.failed`), montant + frais remboursés
Retrait	`0002`	`PROCESSING`, `TIMEOUT` (`withdrawal.under_review`), puis `SUCCESS` (`withdrawal.succeeded`)
Retrait	autre	`PROCESSING` puis `SUCCESS` après ~3 s (`withdrawal.succeeded`)

Exemples : 70120000 (paiement réussi), 70120001 (paiement expiré, retrait en échec), 70120002 (retrait en vérification).

Déclencher l’issue d’un paiement

POST/gatewaytransaction/api/sandbox/payments/{reference}/completeX-API-Key

POST/gatewaytransaction/api/sandbox/payments/{reference}/expireX-API-Key

Pour un paiement de test resté PENDING : complete le passe en SUCCESS et crédite le portefeuille de test, expire le passe en EXPIRED. Le webhook correspondant est envoyé comme en production. La réponse est la transaction à jour.

Vous pouvez aussi le faire depuis votre espace : en mode test, ouvrez la transaction et cliquez sur « Simuler le paiement du client ».

HTTP	cause	Cas
403	`SANDBOX_ONLY`	Appel fait avec une clé de production
409	`INVALID_STATUS`	Paiement déjà terminé
404	`NOT_FOUND`	Référence inconnue (ou paiement de production)

Simuler le paiement du client

curl -X POST "https://paygate.nebyron.com/management/gatewaytransaction/api/sandbox/payments/PAY261005R1A3NKNJGZ/complete" \
  -H "X-API-Key: $NEBRYON_TEST_API_KEY"

Faire expirer le paiement

curl -X POST "https://paygate.nebyron.com/management/gatewaytransaction/api/sandbox/payments/PAY261005R1A3NKNJGZ/expire" \
  -H "X-API-Key: $NEBRYON_TEST_API_KEY"

Réponse

{
  "reference": "PAY261005R1A3NKNJGZ",
  "status": "SUCCESS",
  "operatorReference": "SBX…",
  "environment": "SANDBOX",
  "livemode": false,
  "...": "…"
}

Webhooks et WebSocket

Les webhooks de test partent vers la même URL, signés avec le même secret. Distinguez-les par l’en-tête X-Gateway-Environment: SANDBOX ou le champ livemode: false (dans le corps et dans data).

En production, ignorez tout webhook livemode: false (répondez 200 sans traiter), ou aiguillez-le vers votre environnement de recette : sinon une commande pourrait être validée par un paiement de test.

Une connexion /ws/partner prend l’environnement de sa clé : une connexion de test ne reçoit que des évènements de test, une connexion de production que des évènements réels.

Webhook de test

POST https://votre-site.com/webhooks/gateway
X-Gateway-Event: payment.succeeded
X-Gateway-Environment: SANDBOX
X-Gateway-Signature: sha256=…

{
  "id": "…",
  "event": "payment.succeeded",
  "sequence": 1,
  "livemode": false,
  "createdAt": "…",
  "data": { "environment": "SANDBOX", "livemode": false, "...": "…" }
}

Node.js : ignorer les tests en production

const notification = JSON.parse(req.body);
// En production, ignorer les évènements de test (même URL, même secret).
if (process.env.NODE_ENV === "production" && notification.livemode === false) {
  return res.sendStatus(200);
}

WebSocket : message d’accueil

{ "type": "CONNECTED", "environment": "SANDBOX", "livemode": false, "partner": { "...": "…" }, "serverTime": "…" }

Passer en production

Faites vérifier votre compte (CNIB recto et verso) depuis l’espace partenaire : votre clé de production est générée à la validation.
Affichez-la une seule fois dans Intégration › Clé de production, et stockez-la côté serveur.
Remplacez la clé de test par la clé de production : routes et secret webhook ne changent pas.
Parcourez la liste de contrôle.