Quickstart

By the end of this guide you will have a customer, a subscription and a paid test invoice. It takes about ten minutes.

1. Create an account and a test key

Sign up on the developer portal, then open the sandbox app. Under API Keys, create a qb_test_sk_… key. A test key never reaches Wave and sends no email (see Test mode).

2. Create a customer

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"}'

Note the id that comes back: it is the customer’s.

3. Create a 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}'

Amounts are in XOF. Note the plan’s id.

4. Subscribe the customer

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

The subscription is created. Billing is in arrears: its invoices are raised at the end of each period, not now, so there is nothing to pay yet. The next step creates an invoice you can pay right away.

5. Create and pay a test invoice

Create a manual invoice for the customer (the amount is before tax):

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

Note the invoice’s id, then initiate the payment on it:

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":"<invoice id>","phone_number":"+2250700000000","provider":"wave"}'

Open the redirectUrl that comes back. Choose Pay: the invoice becomes paid and the invoice.paid event is sent. Choose Decline: the payment becomes failed and reminders start.

With the Node SDK

The same calls with the SDK: qbill.customers.create, qbill.plans.create, qbill.subscriptions.create, qbill.invoices.create({ customer, amount: 6000, description, due_date, status: "open" }), then qbill.payments.initiate. The @qbill/node package arrives on npm soon; until then, curl works today.

Next

• Authentication & keys
• Webhooks
• API reference