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.

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

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. Il apparaît uniquement tant que la connexion n'a pas été revendiquée.

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 le webhook account.updated.

3. Attendre l'activation des paiements

Une connexion active ne peut pas encore effectuer de débit. payment_status reste à inactive jusqu'à la validation du contrôle de conformité du marchand. Wajub l'active ensuite et émet account.payment_activated.

curl -X PUT https://api.wajub.com/accounts/acc_test_7Yh2MpL4tRb3nP8sZcXv \
  -H "Authorization: sk_test.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -d '{ "payment_status": "active" }'

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.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "XAF",
    "customer": { "email": "buyer@example.com" },
    "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 lit les règles tarifaires de la connexion, calcule votre commission sur le montant du paiement et la crédite à votre plateforme. Un webhook vous en informe.

Le payload contient également feeable_type. Sa valeur actuelle est le nom de classe interne de l'objet auquel les frais ont été appliqués, pas un type public. Effectuez plutôt la correspondance avec feeable_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.