Démarrage rapide

Quatre appels suffisent pour passer de rien à de l'argent sur votre solde : créez le document, ouvrez sa page, transmettez l'URL au client, puis attendez le paiement. Rien ne se passe automatiquement entre ces étapes. C'est l'erreur la plus fréquente lors d'une première facture.

1. Créer le document

Une facture est créée comme brouillon et le reste jusqu'à ce que vous la fassiez avancer. Sa création enregistre un document numéroté, rien de plus : aucun argent ne circule, aucun e-mail n'est envoyé et le client n'est informé de rien.

Quatre champs sont obligatoires, mais la fiche d'un client n'en fait pas partie. Une facture est adressée à un nom. Vous pouvez donc facturer une personne qui ne vous a encore jamais payé.

La liste complète des champs, les taxes, les remises et le reste se trouvent sur la page Factures. Envoyez cette requête avec une clé secrète live.

curl https://api.wajub.com/invoices \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-amina-september" \
  -d '{
    "customer_name": "Amina Traoré",
    "customer_email": "amina@example.com",
    "invoice_date": "2026-09-11",
    "due_date": "2026-09-25",
    "currency": "XAF",
    "items": [
      { "name": "Consulting, September", "quantity": 3, "unit_price": 150000 }
    ]
  }'

La réponse est 201 Created. Les totaux sont calculés à partir des lignes. subtotal, total et amount_due sont donc renseignés dans la réponse, même si vous ne les avez pas envoyés.

Conservez l'id : tous les appels suivants en ont besoin. invoice_number est la référence lisible imprimée sur le document. Elle se compose de INV-, de l'année et du mois, puis d'un compteur qui repart à 0001 chaque mois.

2. Ouvrir sa page de paiement

Une facture au statut draft ne peut pas être payée. Sa page publique répond 403 This invoice is not available for payment. à toute personne qui l'ouvre. Seuls quatre statuts permettent le paiement : sent, viewed, overdue et partial.

Un appel suffit pour la sortir du statut draft.

curl -X POST https://api.wajub.com/invoices/inv_LRQqYvlhrgUOE225KMKU/send \
  -H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…"

La réponse est 200, avec status: "sent" et sent_at horodaté.

3. Transmettre l'URL

L'envoi vous revient : WhatsApp, SMS, votre propre e-mail ou tout autre moyen déjà utilisé avec ce client. L'adresse correspond à l'identifiant de la facture sur son propre domaine.

https://invoice.wajub.com/inv_LRQqYvlhrgUOE225KMKU

Cette URL ne figure pas dans la réponse de l'API. Construisez-la à partir de l'id conservé. Seul le domaine peut varier : un marchand qui distribue ses factures depuis un domaine personnalisé et vérifié utilise ce domaine. Le Dashboard affiche l'adresse réelle sur la facture.

La page qui s'ouvre est un checkout classique. Elle reprend votre identité visuelle, les lignes de la facture et les opérateurs disponibles pour sa devise. La première fois que le client l'ouvre, la facture passe automatiquement de sent à viewed.

4. Savoir quand elle a été payée

Une facture payée produit deux événements qui ne sont pas interchangeables.

payment.succeeded représente l'argent. Il contient le montant, le canal et la référence du prestataire. C'est cet événement qui doit déclencher la livraison, car lui seul prouve que les fonds ont circulé.

invoice.updated représente le document. Il est émis à chaque modification de la facture. Le paiement n'est qu'une de ces modifications.

Il n'existe aucun événement invoice.paid, invoice.sent ou invoice.overdue. Une facture ne peut émettre que invoice.created, invoice.updated et invoice.deleted. Le statut du payload vous indique donc la transition concernée.

Quand l'argent a été reçu ailleurs

Espèces, virement bancaire ou paiement qui n'est jamais passé par Wajub : enregistrez-le sur le document au lieu de laisser la facture ouverte.

N'envoyez aucun amount pour régler entièrement la facture. Si vous en envoyez un, il est ajouté à amount_paid. La facture reste alors au statut partial jusqu'à ce que le total soit couvert. Une facture annulée ou remboursée refuse l'appel avec 400.

Les statuts et qui les attribue

Vous ne pouvez définir que trois des huit statuts. Les autres résultent des actions du client ou d'une tâche nocturne. Il est utile de le savoir avant de construire votre propre machine à états.