Démarrage rapide

Quatre étapes sont nécessaires, et la troisième ne vous appartient pas. Une connexion devient utilisable uniquement après que le marchand s'est connecté et l'a acceptée. Prévoyez donc un aller-retour avec une personne avant votre premier paiement.

Toutes ces étapes nécessitent la clé secrète de votre plateforme et un plan Scale.

1. Créer la connexion

Vous déclarez ce que la connexion peut faire et ce que vous retiendrez sur celle-ci. Les capacités sont obligatoires et ne peuvent pas être vides. La tarification est facultative. callback est la page sur laquelle le marchand revient après avoir accepté, pas une URL de webhook : aucun événement n'y est jamais envoyé.

curl https://api.wajub.com/accounts \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "shop-amina",
    "capabilities": ["read", "payments", "refunds"],
    "pricing": { "percentage_fee": 2.5, "currency": "XAF" },
    "callback": "https://example.com/connected"
  }'

La réponse est 201 Created. Deux champs sont particulièrement importants.

id est la valeur que vous enverrez dans X-Sync. authorization_url est le lien que le marchand doit ouvrir, et cette réponse est le seul endroit où il apparaît. Envoyez-le ou conservez-le maintenant, car une lecture ultérieure du sous-compte ne le renvoie pas. POST /accounts/{id}/token en génère un nouveau.

2. Envoyer son lien au marchand

Présentez authorization_url au marchand par le moyen qui vous convient : un e-mail, un bouton dans votre propre parcours d'intégration ou un code QR. Il ouvre le lien, se connecte à son compte Wajub, examine les capacités demandées, puis accepte.

Après son acceptation, status passe à active et slave contient le nom et l'adresse e-mail de son entreprise. Vous le découvrez en interrogeant régulièrement le compte ou en recevant account.connected sur l'un des endpoints de webhook de votre plateforme. Enregistrez l'endpoint dans le Dashboard ou avec POST /webhooks et abonnez-le à account.connected par son nom : un abonnement * ne le reçoit pas. Livraisons du cycle de vie Sync décrit ce qui arrive.

3. Attendre l'activation des paiements

En sandbox, payment_status passe à active dès que le marchand accepte, et vous pouvez débiter immédiatement. En live, cela dépend du marchand : déjà vérifié, la connexion est active tout de suite ; encore en cours de vérification, elle reste inactive jusqu'à la validation, puis Wajub envoie account.payment_activated. Une connexion lite attend aussi que le rail Wajub soit accordé au marchand.

4. Recevoir un paiement sur la connexion

Vous utilisez désormais l'API de paiement classique. Un seul en-tête détermine le propriétaire du paiement.

curl https://api.wajub.com/payments \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "XAF",
    "customer": { "email": "[email protected]" },
    "callback": "https://example.com/return"
  }'

Le paiement appartient désormais au marchand. Il apparaît dans son Dashboard, est réglé sur son solde et déclenche ses webhooks. Les vôtres sont aussi déclenchés avec une copie du même événement.

Ce que vous recevez après sa réussite

Lorsque le paiement est terminé, Wajub applique la tarification de la connexion, calcule votre commission sur le montant du paiement et la crédite à votre plateforme. Un webhook vous en informe.

Le reference sous account répète l'id de la connexion au lieu de votre propre référence. Rapprochez les commissions par connexion, sur account.id.

Le marchand reçoit l'événement inverse, fee.charged, sur ses propres endpoints. Grâce à ces deux événements, chaque partie peut contrôler la commission sans interroger l'autre.