Bac à sable

Le bac à sable fait tourner Futa avec des émetteurs synthétiques : chaque paiement, remboursement et webhook est réel pour la plateforme et ne déplace aucun argent. Aucun téléphone ne reçoit de demande, et aucun PIN ni mot de passe de l’émetteur n’est jamais demandé. Futa en héberge un pour les testeurs qu’il invite, et vous pouvez aussi le faire tourner en local, depuis les dépôts Futa.

Le bac à sable hébergé

Le bac à sable hébergé est public mais sur invitation seulement, et tout y est synthétique :

Testeurs invités seulement. Futa crée le compte de chaque testeur, une adresse synthétique en @futa.invalid, et lui remet un mot de passe temporaire ; il n’y a ni inscription ni réinitialisation du mot de passe. La première connexion demande un nouveau mot de passe et configure une application d’authentification, dont chaque connexion demande ensuite le code.
Argent synthétique seulement. Clés de test, les six payeurs de test et des émetteurs synthétiques : aucun paiement, remboursement ni versement ne déplace d’argent réel, et les clés de production sont refusées.
KYB synthétique seulement. Les informations et les justificatifs KYB d’un commerce de test sont inventés pour l’essai : n’envoyez jamais une vraie pièce d’identité, un vrai extrait d’immatriculation ou un vrai justificatif de domicile.
Aucune donnée réelle. Aucun nom, numéro de téléphone, adresse électronique ni document d’une personne réelle n’entre dans un paiement, une référence, une description ou le portail.

Service	Adresse
API marchande, le premier serveur du contrat	`https://api.sandbox.futa-app.com`, ses routes `/v1`
Page de paiement hébergée	`https://checkout.sandbox.futa-app.com`
Console développeur : clés de test, webhooks et journal des requêtes	`https://console.sandbox.futa-app.com`
Portail marchand	`https://portal.sandbox.futa-app.com`
Destination des webhooks	Le récepteur de test du bac à sable, `http://127.0.0.1:18161/sandbox/webhooks` chez Futa, jamais votre serveur : il répond à chaque livraison sans en garder aucune, et la console développeur les liste

Les webhooks ne quittent jamais Futa, si bien que votre serveur n’en reçoit aucun du bac à sable hébergé. Un commerce de test démarre sans point de réception ; dans la page Webhooks de la console développeur, ajoutez-en un sur le récepteur de test, http://127.0.0.1:18161/sandbox/webhooks, que la console nomme « Récepteur de test 2 du sandbox ». Il répond 204 à chaque livraison dont la Futa-Signature est bien formée et récente, ne vérifie aucune signature avec votre secret et ne garde rien, si bien que le « Journal de livraison » liste chaque livraison avec son événement, ses tentatives et le statut que chacune a reçu (les webhooks dans le bac à sable hébergé). Le premier récepteur de la console, http://127.0.0.1:18160/sandbox/webhooks, n’accepte que les livraisons du commerce du bac à sable propre à Futa et répond 401 aux vôtres ; le troisième n’a aucun auditeur dans le bac à sable hébergé. GET /v1/payments/{id} donne l’état qui fait autorité de chaque paiement. Les livraisons vers vos propres serveurs attendent la vérification des destinations et le contrôle des sorties.

Clés de test

Dans le bac à sable hébergé, la console développeur s’ouvre aux membres d’un commerce de test : si votre compte n’est membre d’aucun, créez-en d’abord un dans le portail marchand, « Créez votre commerce de test. », qui vous en fait le propriétaire. Créez ensuite la clé de votre serveur dans la console développeur : « Clés API », puis « Créer une clé restreinte », avec les permissions dont elle a besoin, comme payments:read, payments:write, webhooks:read et webhooks:manage. Sur votre machine, la clé d’amorçage du bac à sable l’émet (le faire tourner en local). Dans les deux cas, le secret commence par sk_test_ et n’est montré qu’une fois.

Envoyez les clés en Authorization: Bearer sk_test_… depuis votre serveur uniquement, jamais depuis le navigateur ou l’application d’un payeur. Une clé n’accorde jamais keys:manage. Les clés de production, sk_live_…, sont refusées : le mode réel attend la production, et un dossier KYB approuvé ne débloque rien à lui seul.

Payeurs de test

Six numéros synthétiques choisissent le résultat d’un paiement, saisis au paiement ou envoyés comme msisdn avec method: "simulator" pour un paiement direct. Aucun autre numéro n’est accepté.

Numéro	Résultat
`+243810000001`	Approuvé
`+243810000002`	Refusé
`+243810000003`	Expiration, telle que l’émetteur la déclare
`+243810000004`	Incertain, puis escaladé aux opérations
`+243810000005`	Approuvé après la fenêtre d’approbation
`+243810000006`	Émetteur indisponible, puis vérifié à nouveau

Minuteries

Le payeur a 120 secondes pour approuver, et un paiement incertain est vérifié pendant 15 minutes avant que les opérations le prennent en charge. Le bac à sable hébergé garde ces minuteries ; sur votre machine, vous pouvez les raccourcir pour un essai rapide.

Les relances de facture suivent l’horloge de Kinshasa, à 09:00 les jours que nomme la politique de leur lot. Une clé de test qui a invoices:write les lance aussitôt pour ses propres lots avec POST /v1/sandbox/invoice-reminders/run, en se plaçant à n’importe quel instant de maintenant à 100 jours plus tard, SYNTHETIC ; seul le bac à sable sert cette route, et ses messages n’atteignent aucun téléphone : voir le lancement des relances du bac à sable.

Bibliothèques clientes

Futa ne publie encore aucune bibliothèque cliente. Les clients TypeScript des API marchande et payeur sont générés à côté de cette documentation depuis leurs contrats et vérifiés par rapport à eux, mais aucun n’est empaqueté ni publié. L’ouvreur du paiement intégré est servi par le paiement hébergé lui-même, à /sdk/v1/checkout.js ; les SDK mobiles et l’extension WooCommerce se construisent depuis leurs sources et ne sont pas encore distribués. Appelez l’API en HTTP, comme le font les exemples cURL, Node, PHP et Python de ces pages : le contrat publié, openapi.json, décrit chaque opération publique, et le guide des webhooks relie les schémas des événements.

Le faire tourner en local

Le même bac à sable tourne sur votre machine depuis les dépôts Futa, ses secrets dans votre propre sandbox/.env. C’est lui qu’utilisent les étapes locales de ces pages ; dans le bac à sable hébergé, vous n’avez besoin d’aucune.

Le démarrer

Gardez les dépôts Futa côte à côte, installez Java 21 et Docker Compose, et laissez au moins 8 Go d’espace disque libre. Depuis Futa-platform :

python3 scripts/sandbox.py init
python3 scripts/sandbox.py up
python3 scripts/sandbox.py build
python3 scripts/sandbox.py start
python3 scripts/sandbox.py cdc

init écrit des identifiants privés dans sandbox/.env et les conserve aux lancements suivants. Démarrez le switch avant cdc, pour que ses migrations de base de données existent. stop arrête les services ; down arrête les conteneurs et conserve leurs données.

Service	Adresse
API marchande, le second serveur du contrat	`http://127.0.0.1:18130`
Page de paiement hébergée	`http://127.0.0.1:18140`
Destinations de webhooks autorisées	`http://127.0.0.1:18160/sandbox/webhooks`, le récepteur du service des canaux, où démarre le point de réception du commerce du bac à sable ; pour votre propre récepteur, `http://127.0.0.1` sur un port de 18161 à 18169 à son propre chemin (au plus 512 caractères) avec une chaîne de requête facultative (au plus 512)

Ses clés de test

MERCHANT_API_KEY, dans sandbox/.env, est la clé d’amorçage du bac à sable : ne l’utilisez que pour émettre les clés de votre serveur. POST /v1/keys avec elle crée une clé restreinte dont le secret commence par sk_test_ et n’est montré qu’une fois :

{
  "label": "Order service",
  "permissions": ["payments:read", "payments:write", "webhooks:read", "webhooks:manage"]
}

Des minuteries plus courtes

Pour un essai rapide, redémarrez avec des minuteries plus courtes, puis lancez les suites de vérification :

python3 scripts/sandbox.py stop
APPROVAL_SECONDS=5 UNCERTAINTY_SECONDS=12 python3 scripts/sandbox.py start
python3 scripts/verify-sandbox.py --restart
python3 scripts/verify-recovery.py

stop puis start sans ces variables rétablissent les minuteries normales. Futa-platform/sandbox/README.md traite des diagnostics.

Ce qui attend la production

Les participants réels, les clés et versements de production, le déploiement en production et ses adresses ne font pas partie du bac à sable, hébergé ou local. Un versement du bac à sable n’atteint que les participants synthétiques du simulateur, avec de l’argent synthétique, des frais nuls synthétiques et des plafonds et des seuils SYNTHETIC : consultez le guide des versements. docs/prd-traceability.md, dans Futa-platform, liste ce qui reste à faire.