Démarrage rapide

À la fin de ce guide, vous aurez un client, un abonnement et une facture de test payée. Comptez une dizaine de minutes.

1. Créer un compte et une clé de test

Créez votre compte sur le portail développeur, puis ouvrez l’application sandbox. Dans Clés API, créez une clé qb_test_sk_…. Une clé de test n’atteint jamais Wave et n’envoie aucun e-mail (voir Mode test).

2. Créer un client

curl -X POST https://api.qbill.dev/v1/customers \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"name":"Boutique Awa","email":"awa@example.com","country":"CI"}'

Notez l’id renvoyé : c’est celui du client.

3. Créer un plan

curl -X POST https://api.qbill.dev/v1/plans \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"name":"Pro","pricing_model":"flat_rate","amount_monthly":6000}'

Les montants sont en XOF. Notez l’id du plan.

4. Abonner le client

curl -X POST https://api.qbill.dev/v1/subscriptions \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"customer":"<id du client>","plan":"<id du plan>","billing_interval":"monthly"}'

L’abonnement est créé. La facturation se fait à terme échu : ses factures sont émises à la fin de chaque période, pas maintenant, il n’y a donc encore rien à payer. L’étape suivante crée une facture que vous pouvez payer tout de suite.

5. Créer et payer une facture de test

Créez une facture manuelle pour le client (le montant est hors taxes) :

curl -X POST https://api.qbill.dev/v1/invoices \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"customer":"<id du client>","amount":6000,"description":"Pro, premier mois","due_date":"2026-12-31","status":"open"}'

Notez l’id de la facture, puis initiez le paiement dessus :

curl -X POST https://api.qbill.dev/v1/payments/initiate \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"invoice_id":"<id de la facture>","phone_number":"+2250700000000","provider":"wave"}'

Ouvrez le redirectUrl renvoyé. Cliquez sur Pay : la facture passe à paid et l’événement invoice.paid est envoyé. Cliquez sur Decline : le paiement passe à failed et les relances démarrent.

Avec le SDK Node

Les mêmes appels avec le SDK : qbill.customers.create, qbill.plans.create, qbill.subscriptions.create, qbill.invoices.create({ customer, amount: 6000, description, due_date, status: "open" }) puis qbill.payments.initiate. Le paquet @qbill/node arrive bientôt sur npm ; en attendant, curl fonctionne dès aujourd’hui.

Ensuite

• Authentification et clés
• Webhooks
• Référence API