Démarrage rapide

Un premier paiement de bout en bout, en mode test : création, paiement simulé du client, webhook signé, solde crédité.

1. Créer un compte et une clé API

1. Créez votre compte, puis activez la double authentification dans Paramètres.
2. Dans Développeurs › Clés API, créez une clé secrète. Elle commence par gsp_test_sk_ et ne s’affiche qu’une fois : copiez-la dans la configuration de votre serveur.

2. Créer un paiement

export GALSEN_SECRET_KEY="gsp_test_sk_..."   # votre clé secrète de test

curl -sX POST https://backend.v1.pay.galsen.tech/v1/payment-intents \
  -H "Authorization: Bearer $GALSEN_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XOF",
    "provider": "SANDBOX",
    "customer": { "phone": "+221771234567" },
    "description": "Commande #123",
    "metadata": { "commande": "123" }
  }'

La réponse contient l’identifiant du paiement, son statut et l’adresse où envoyer le client :

{
  "success": true,
  "data": {
    "id": "6f1c…",
    "reference": "GSP-8K2M4Q7T1Z9X",
    "status": "PENDING",
    "provider": "SANDBOX",
    "amount": 10000,
    "currency": "XOF",
    "fees": { "providerFee": 100, "galsenFee": 100 },
    "netAmount": 9800,
    "nextAction": { "type": "redirect", "url": "https://sandbox.pay.invalid/c/sbx_…" },
    "clientSecret": "pi_secret_…",
    "expiresAt": "…"
  },
  "requestId": "…"
}

En production, vous redirigez le client vers data.nextAction.url : il paie sur la page du fournisseur. Les frais ci-dessus sont des valeurs de démonstration ; les vôtres dépendent de votre grille tarifaire.

3. Simuler le client

En mode test, l’adresse sandbox.pay.invalid n’existe pas : c’est vous qui jouez le client, en désignant le paiement par son identifiant (ou par la référence du simulateur, dernier segment de cette adresse).

curl -sX POST https://backend.v1.pay.galsen.tech/v1/sandbox/payments/<id du paiement>/simulate \
  -H "Authorization: Bearer $GALSEN_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "succeed" }'

Le simulateur envoie à Galsen Pay un webhook signé, traité exactement comme celui d’un vrai fournisseur : vérification de la signature, confirmation, écriture comptable. Vous pouvez aussi cliquer sur « Le client paie » dans la fiche du paiement, sur le tableau de bord.

4. Vérifier le résultat

curl -s https://backend.v1.pay.galsen.tech/v1/payment-intents/<id> -H "Authorization: Bearer $GALSEN_SECRET_KEY"   # "status": "SUCCEEDED"
curl -s https://backend.v1.pay.galsen.tech/v1/balance -H "Authorization: Bearer $GALSEN_SECRET_KEY"                # le montant net apparaît

Le montant net arrive d’abord en pending (en attente de règlement), puis passe en available après le délai de règlement de votre compte.

5. Recevoir les webhooks

Dans Développeurs › Webhooks, indiquez une adresse https publique. Votre serveur recevra payment.succeeded au prochain paiement réussi : c’est le signal fiable pour livrer la commande. Voir Webhooks pour vérifier la signature.