Logo GenukaGenuka Pay
Référence APIAbonnements

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/invoices
  • GET /api/v1/invoices/{id}
  • GET /api/v1/invoices/{id}/pdf
  • POST /api/v1/invoices/{id}/payment-requests
  • POST /api/v1/invoices/{id}/manual-payments
  • POST /api/v1/invoices/{id}/remind
  • POST /api/v1/invoices/{id}/shift-due-date
  • POST /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"
  }
}
ChampDescription
numberNuméro sans trou, propre à chaque application : INV-000001, INV-000002… Sandbox et live sont numérotés séparément.
statusopen, 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_endPériode facturée. period_end est le début de la période suivante.
amount_dueMontant de la formule au moment de l'émission
amount_paidMontant payé et affecté à cette facture
credit_appliedCrédit du client utilisé sur cette facture
amount_remainingReste à payer : amount_due − amount_paid − credit_applied, jamais négatif
due_atDate d'échéance, à minuit heure de votre entreprise
paid_atDate du paiement qui a soldé la facture
payment_urlPage de paiement publique à partager avec le client, sans connexion
pdf_urlPDF public de la facture
paymentsPaiements reçus, avec include=payments (voir ci-dessous)

Statuts

StatutSignification
openÀ payer
paidSoldée. Définitif.
voidAnnulée par vous, ou parce que l'abonnement s'est terminé. Définitif.
uncollectibleResté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

ChampDescription
sourcepush (demande de paiement mobile money), page (payé sur la page de la facture), manual (espèces enregistrées par vous) ou credit
amountMontant reçu, trop-perçu compris
payin_idTransaction mobile money, pour push et page
paid_atDate du paiement
noteVotre 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ètreDescription
filter[status]Un ou plusieurs statuts, par exemple open
filter[customer_id]Factures d'un client
filter[subscription_id]Factures d'un abonnement
includepayments pour joindre les paiements
sortcreated_at, due_at ou amount_due, préfixe - pour l'ordre décroissant. Par défaut -created_at.
page, per_pagePagination (liste uniquement)

Obtenir le PDF

GET /api/v1/invoices/{id}/pdf

Renvoie 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-requests

Envoie au client une demande de paiement (push USSD) pour le reste à payer. Il la valide sur son téléphone.

ParamètreTypeRequisDescription
phonestringNonNumé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)."
  }
}
statusCode HTTPSignification
started202Demande envoyée, le client valide sur son téléphone
redirect_required202L'opérateur ne permet pas le push (Wave, Orange Côte d'Ivoire…) : envoyez le client sur redirect_url
already_in_flight200Un paiement est déjà en cours sur cette facture, rien de nouveau n'est lancé
failed200Rien 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-payments

Pour 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ètreTypeRequisDescription
amountintegerNonMontant reçu, en unité mineure. Par défaut, le reste à payer.
paid_atdatetimeNonDate du paiement, maintenant par défaut. Pas dans le futur.
notestringNon500 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}/remind

Sans 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"
  }
}
  • 202 quand un message part, status à queued. Pendant les heures de silence (21 h – 8 h par défaut, heure de votre entreprise), il vaut deferred et scheduled_for donne l'heure d'envoi.
  • 200 avec status: "skipped" quand le client n'a aucun contact joignable.
  • Une relance manuelle par facture et par heure. Au-delà : 429 reminder_rate_limited, avec l'en-tête Retry-After en 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-date

Geste commercial : repousse l'échéance d'une facture ouverte.

ParamètreTypeRequisDescription
due_atstringOuiNouvelle 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ètreTypeRequisDescription
replacebooleanNonÉmettre une facture de remplacement. true par défaut tant que l'abonnement facture encore cette période.
due_atstringNonÉ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 HTTPCodeCas
402free_plan_manual_paymentsPaiement en espèces enregistré sur l'offre Gratuite (live, sans l'option payante)
404Facture inconnue, d'une autre entreprise ou de l'autre environnement
422invoice_not_openLa facture n'est plus ouverte
422partial_payment_not_supportedPaiement manuel inférieur au reste à payer
422payment_in_progressRelance pendant qu'un paiement est en cours
422due_date_not_laterNouvelle échéance qui n'est pas plus tardive
422invoice_not_replaceableRemplacement demandé alors que l'abonnement ne facture plus cette période
429reminder_rate_limitedRelance manuelle moins d'une heure après la précédente

How is this guide?

Last updated on