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.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-amina-september" \
  -d '{
    "customer_name": "Amina Traoré",
    "customer_email": "[email protected]",
    "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 vaut encore null. La référence lisible imprimée sur le document est attribuée à l'étape suivante, selon la numérotation de votre compte, la même séquence que celle du Dashboard : INV- (ou le préfixe que vous avez choisi), l'année, puis un compteur qui repart à 0001 chaque année.

2. Ouvrir sa page de paiement

Une facture au statut draft ne peut pas être payée. Sa page publique répond 404 Invoice not found. à 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.xxxxxxxxxxxxxxxx…"

La réponse est 200, avec status: "sent", sent_at horodaté et le invoice_number attribué. L'appel envoie aussi à customer_email un e-mail avec le lien de la facture et une copie PDF en pièce jointe. Le rappeler plus tard renvoie l'e-mail et renseigne de nouveau sent_at, sans changer le statut.

L'appel refuse d'envoyer à personne. Sans customer_email, et sans customer_id dont le client a un e-mail, il répond 422 sur customer_email et la facture reste un brouillon. Une facture déjà paid, cancelled ou refunded répond 400.

3. Transmettre l'URL

L'e-mail ne suffit pas toujours : c'est peut-être par WhatsApp ou par SMS que vous joignez vraiment ce client. L'adresse à partager 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.

Si vous n'avez pas renseigné customer_email, /send refuse la facture : envoyez-la plutôt depuis le Dashboard, qui ouvre sa page sans envoyer d'e-mail. La page affiche alors au payeur un champ e-mail au-dessus du bouton de paiement et n'ouvre le paiement qu'une fois ce champ rempli. Cette adresse reçoit la confirmation du paiement et son reçu, et elle est inscrite sur la facture comme son customer_email (invoice.updated est envoyé) : les échéances suivantes et /send l'utilisent.

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.

Deux autres événements suivent l'argent du côté du document. invoice.payment_succeeded arrive pour chaque paiement effectué sur la page de la facture, échéance comprise, et invoice.paid une fois la facture réglée en totalité. Tous deux portent la facture. Il n'existe aucun invoice.sent ni invoice.overdue : pour ceux-là, le statut du payload d'un invoice.updated vous indique la transition concernée. Et payment.succeeded désigne la facture payée dans son champ invoice.

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, supérieur à zéro, il est ajouté à amount_paid. La facture reste alors au statut partial jusqu'à ce que le total soit couvert. Un brouillon, une facture déjà payée, annulée ou remboursée refusent l'appel avec 400 ; un amount nul répond 422.

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 de Wajub, pendant la nuit. Il est utile de le savoir avant de construire votre propre machine à états.