Factures
Suivez les factures de vos abonnements, encaissez-les par mobile money ou en espèces, relancez et ajustez les échéances.
Genuka Pay émet une facture par période d'abonnement. Vous ne créez jamais de facture vous-même : vous les lisez, les faites payer et les ajustez.
Endpoints
GET /api/v1/invoicesGET /api/v1/invoices/{id}GET /api/v1/invoices/{id}/pdfPOST /api/v1/invoices/{id}/payment-requestsPOST /api/v1/invoices/{id}/manual-paymentsPOST /api/v1/invoices/{id}/remindPOST /api/v1/invoices/{id}/shift-due-datePOST /api/v1/invoices/{id}/void
L'objet facture
{
"data": {
"id": "01k7a3m2x8q9w4e5r6t7y8z9v0",
"object": "invoice",
"number": "INV-000042",
"status": "open",
"customer_id": "01k79zz1c2v3b4n5m6p7k8j9h0",
"customer": { "id": "01k79zz1c2v3b4n5m6p7k8j9h0", "name": "Awa Ndiaye" },
"subscription_id": "01k7a3m2a1s2d3f4g5h6j7k8m9",
"period_start": "2026-10-09T23:00:00.000000Z",
"period_end": "2026-11-09T23:00:00.000000Z",
"amount_due": 15000,
"amount_paid": 0,
"credit_applied": 0,
"amount_remaining": 15000,
"currency": "XAF",
"due_at": "2026-10-09T23:00:00.000000Z",
"paid_at": null,
"payment_url": "https://pay.genuka.com/billing/invoices/...",
"pdf_url": "https://pay.genuka.com/billing/invoices/.../pdf",
"created_at": "2026-10-06T08:00:00.000000Z"
}
}| Champ | Description |
|---|---|
| number | Numéro sans trou, propre à chaque application : INV-000001, INV-000002… Sandbox et live sont numérotés séparément. |
| status | open, paid, void ou uncollectible. Voir ci-dessous. |
| customer | { id, name }, sur la liste, la lecture, l'encaissement manuel et dans les webhooks |
| period_start, period_end | Période facturée. period_end est le début de la période suivante. |
| amount_due | Montant de la formule au moment de l'émission |
| amount_paid | Montant payé et affecté à cette facture |
| credit_applied | Crédit du client utilisé sur cette facture |
| amount_remaining | Reste à payer : amount_due − amount_paid − credit_applied, jamais négatif |
| due_at | Date d'échéance, à minuit heure de votre entreprise |
| paid_at | Date du paiement qui a soldé la facture |
| payment_url | Page de paiement publique à partager avec le client, sans connexion |
| pdf_url | PDF public de la facture |
| payments | Paiements reçus, avec include=payments (voir ci-dessous) |
Statuts
| Statut | Signification |
|---|---|
open | À payer |
paid | Soldée. Définitif. |
void | Annulée par vous, ou parce que l'abonnement s'est terminé. Définitif. |
uncollectible | Restée impayée jusqu'à la fin de l'abonnement. Définitif. |
Une facture est émise 3 jours avant son échéance (1 jour pour une formule hebdomadaire). La première facture d'un abonnement sans essai est émise à sa création. Le crédit du client est utilisé dès l'émission et peut solder la facture à lui seul.
Un paiement qui arrive sur une facture déjà soldée ou annulée n'est pas perdu : il devient du crédit pour le client (invoice.updated avec context.reason: "duplicate_payment").
Les paiements d'une facture
| Champ | Description |
|---|---|
| source | push (demande de paiement mobile money), page (payé sur la page de la facture), manual (espèces enregistrées par vous) ou credit |
| amount | Montant reçu, trop-perçu compris |
| payin_id | Transaction mobile money, pour push et page |
| paid_at | Date du paiement |
| note | Votre note. Une mention est ajoutée quand une partie est passée en crédit. |
Lister et lire les factures
GET /api/v1/invoices
GET /api/v1/invoices/{id}| Paramètre | Description |
|---|---|
| filter[status] | Un ou plusieurs statuts, par exemple open |
| filter[customer_id] | Factures d'un client |
| filter[subscription_id] | Factures d'un abonnement |
| include | payments pour joindre les paiements |
| sort | created_at, due_at ou amount_due, préfixe - pour l'ordre décroissant. Par défaut -created_at. |
| page, per_page | Pagination (liste uniquement) |
Obtenir le PDF
GET /api/v1/invoices/{id}/pdfRenvoie le lien du PDF, pas le fichier : {"data": {"url": "https://pay.genuka.com/billing/invoices/.../pdf"}}. Ce lien est public et sans authentification : le jeton qu'il contient fait office de secret. Le PDF est rendu dans la langue du client, à votre marque, avec le détail de la période, les paiements reçus et un tampon PAYÉE ou ANNULÉE.
Demander un paiement mobile money
POST /api/v1/invoices/{id}/payment-requestsEnvoie au client une demande de paiement (push USSD) pour le reste à payer. Il la valide sur son téléphone.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| phone | string | Non | Numéro au format E.164. Par défaut, le payment_phone de l'abonnement. |
{
"data": {
"status": "started",
"payin_id": "01k7d1e2f3g4h5j6k7m8n9p0q1",
"track_id": "PX-01k7d1e2f3g4h5j6k7m8n9p0q1",
"redirect_url": null,
"message": "Approve the payment of 15,000 XAF on your phone (+237670000001)."
}
}status | Code HTTP | Signification |
|---|---|---|
started | 202 | Demande envoyée, le client valide sur son téléphone |
redirect_required | 202 | L'opérateur ne permet pas le push (Wave, Orange Côte d'Ivoire…) : envoyez le client sur redirect_url |
already_in_flight | 200 | Un paiement est déjà en cours sur cette facture, rien de nouveau n'est lancé |
failed | 200 | Rien n'a été lancé : facture déjà payée, pas de numéro, numéro sans mobile money… Le détail est dans message. |
message est rédigé pour être montré au client, dans la langue de la requête. Une facture n'accepte qu'un paiement à la fois : la demande suivante est bloquée jusqu'à 3 minutes, ou jusqu'à l'issue du paiement en cours.
Le résultat arrive par webhook : invoice.paid (avec context.source: "push") puis l'événement d'abonnement, ou invoice.payment_failed. Vous pouvez aussi suivre la transaction avec son track_id sur GET /payments/status/{track_id}. Le numéro qui a payé devient le payment_phone de l'abonnement, et le client reçoit un reçu. La transaction sous-jacente émet aussi les webhooks transaction.* habituels.
En sandbox, utilisez les numéros de test pour choisir l'issue du paiement.
Enregistrer un paiement en espèces
POST /api/v1/invoices/{id}/manual-paymentsPour un paiement reçu hors de Genuka Pay, au guichet par exemple. Aucun argent ne transite par Genuka Pay et aucun frais n'est prélevé.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| amount | integer | Non | Montant reçu, en unité mineure. Par défaut, le reste à payer. |
| paid_at | datetime | Non | Date du paiement, maintenant par défaut. Pas dans le futur. |
| note | string | Non | 500 caractères au plus |
Indisponible sur l'offre Gratuite (live, sans l'option payante) : 402 free_plan_manual_payments. En sandbox, toujours disponible.
Le paiement doit solder la facture : un montant inférieur au reste à payer est refusé (partial_payment_not_supported). Un montant supérieur solde la facture et le surplus devient du crédit pour le client.
Réponse 201 : la facture avec ses paiements. L'abonnement passe active (ou est renouvelé, ou réactivé). Webhooks : invoice.paid (context.source: "manual"), puis l'événement d'abonnement.
Relancer le client
POST /api/v1/invoices/{id}/remindSans corps. Envoie tout de suite le rappel adapté au moment : facture à venir, due aujourd'hui, en retard, ou abonnement suspendu. Le message part sur le contact préféré du client, puis sur les autres canaux si besoin.
{
"data": {
"message_id": "01k7c8d9e0f1g2h3j4k5m6n7p8",
"status": "deferred",
"scheduled_for": "2026-10-21T07:00:00.000000Z"
}
}202quand un message part,statusàqueued. Pendant les heures de silence (21 h – 8 h par défaut, heure de votre entreprise), il vautdeferredetscheduled_fordonne l'heure d'envoi.200avecstatus: "skipped"quand le client n'a aucun contact joignable.- Une relance manuelle par facture et par heure. Au-delà :
429reminder_rate_limited, avec l'en-têteRetry-Afteren secondes.
Aucun webhook n'est émis. Le message apparaît dans l'historique du client.
Reporter l'échéance
POST /api/v1/invoices/{id}/shift-due-dateGeste commercial : repousse l'échéance d'une facture ouverte.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| due_at | string | Oui | Nouvelle date AAAA-MM-JJ, heure de votre entreprise, plus tardive que l'échéance actuelle |
Les relances et le délai de grâce repartent de la nouvelle date. Un abonnement en retard sur cette facture retrouve ce que la nouvelle date lui accorde : suspended repasse past_due (accès rétabli) si le délai de grâce compté depuis la nouvelle date court encore, et past_due repasse active si le lendemain de la nouvelle date n'est pas encore arrivé. Un abonnement dont l'essai s'est terminé impayé reste past_due. Webhooks : invoice.updated (context.reason: "due_date_shifted"), et subscription.updated si le statut change.
Annuler une facture
POST /api/v1/invoices/{id}/void| Paramètre | Type | Requis | Description |
|---|---|---|---|
| replace | boolean | Non | Émettre une facture de remplacement. true par défaut tant que l'abonnement facture encore cette période. |
| due_at | string | Non | Échéance de la facture de remplacement AAAA-MM-JJ, aujourd'hui ou plus tard. Par défaut, celle de la facture annulée. |
La facture passe void. Le crédit qu'elle avait utilisé est rendu au client, et l'argent déjà payé dessus devient du crédit. Avec replace, une nouvelle facture est émise pour la même période et le même montant, avec un nouveau numéro et un nouveau lien de paiement. Elle est renvoyée dans meta.replacement.
Sans remplacement, la période n'est plus jamais facturée. Webhooks : invoice.voided, puis invoice.created pour la facture de remplacement.
Erreurs
| Code HTTP | Code | Cas |
|---|---|---|
402 | free_plan_manual_payments | Paiement en espèces enregistré sur l'offre Gratuite (live, sans l'option payante) |
404 | Facture inconnue, d'une autre entreprise ou de l'autre environnement | |
422 | invoice_not_open | La facture n'est plus ouverte |
422 | partial_payment_not_supported | Paiement manuel inférieur au reste à payer |
422 | payment_in_progress | Relance pendant qu'un paiement est en cours |
422 | due_date_not_later | Nouvelle échéance qui n'est pas plus tardive |
422 | invoice_not_replaceable | Remplacement demandé alors que l'abonnement ne facture plus cette période |
429 | reminder_rate_limited | Relance manuelle moins d'une heure après la précédente |
How is this guide?
Last updated on