Composer une facture
POST/v1/invoices
Elle naît en brouillon : pas de numéro, pas de lien, rien ne part.
Une ligne peut venir de votre catalogue (« product », « price ») : elle garde tout de même sa désignation et son prix, ce qui a été vendu ce jour-là.
Les en-têtes
Idempotency-KeytexteConseillée : rejouée, la même clé rend la première réponse au lieu de refaire le geste.
Idempotency-KeytexteConseillée : rejouée, la même clé rend la première réponse au lieu de refaire le geste.
Ce qu’on envoie
Un corps JSON. Ce qui n’est pas requis peut être omis.
customerREQUIStexteLe client facturé : un client de l’espace, pas archivé.
currencytexteSans précision : la monnaie de l’espace.
linesREQUISliste de objetSes lignes : de une à cinquante.
due_dateentierL’échéance, en secondes depuis 1970. Sans elle, le délai réglé chez Payiz.
notetexteCe que la facture dit au client, sous les lignes.
fees_paid_by« merchant » · « customer »« customer » : les frais s’ajoutent au paiement, pas à la facture.
template« classic » · « banner » · « detailed » · « ticket »Le dessin voulu pour celle-ci. Sans rien, celui de la boutique.
customerREQUIStexteLe client facturé : un client de l’espace, pas archivé.
currencytexteSans précision : la monnaie de l’espace.
linesREQUISliste de objetSes lignes : de une à cinquante.
due_dateentierL’échéance, en secondes depuis 1970. Sans elle, le délai réglé chez Payiz.
notetexteCe que la facture dit au client, sous les lignes.
fees_paid_by« merchant » · « customer »« customer » : les frais s’ajoutent au paiement, pas à la facture.
template« classic » · « banner » · « detailed » · « ticket »Le dessin voulu pour celle-ci. Sans rien, celui de la boutique.
La demande
bash
curl https://api.payiz.app/v1/invoices \
-H "Authorization: Bearer sk_test_…" \
-H "Idempotency-Key: factures-creer-01" \
-H "Content-Type: application/json" \
-d '{
"customer": "cli_01j9xn4rt6m8wqv2hc5d",
"currency": "XOF",
"lines": [
{
"description": "Pagne wax 6 yards",
"detail": "bleu indigo",
"product": "prd_01j9xm2hp7t4wzq6vc3k",
"price": "prx_01j9xm3kq8v2tzr5wd7n",
"quantity": 2,
"unit_amount": 10000
},
{
"description": "Retouches",
"detail": "ourlet et cintrage",
"quantity": 1,
"unit_amount": 4000,
"discount": 1000
}
],
"note": "Merci de votre confiance."
}'La réponse
json
{
"object": "invoice",
"id": "fac_01j9xp6vb2n4rtw8kd3m",
"number": "FAC-2026-0045",
"customer": "cli_01j9xn4rt6m8wqv2hc5d",
"customer_name": "Awa Houénou",
"customer_email": "awa.h@exemple.bj",
"customer_phone": "+229 01 •• •• 21 07",
"status": "open",
"overdue": false,
"currency": "XOF",
"subtotal": 23000,
"total_discount": 1000,
"total_tax": 4140,
"total": 27140,
"fees_paid_by": "merchant",
"template": null,
"note": "Merci de votre confiance.",
"lines": [
{
"object": "invoice_line",
"id": "lgf_01j9xp8wd3k5tzm7qr2v",
"description": "Pagne wax 6 yards",
"detail": "bleu indigo",
"product": "prd_01j9xm2hp7t4wzq6vc3k",
"price": "prx_01j9xm3kq8v2tzr5wd7n",
"quantity": 2,
"unit_amount": 10000,
"discount": 0,
"tax_rate_bps": 1800,
"amount": 20000,
"tax": 3600
},
{
"object": "invoice_line",
"id": "lgf_01j9xp8wd3k5tzm7qr2w",
"description": "Retouches",
"detail": "ourlet et cintrage",
"product": null,
"price": null,
"quantity": 1,
"unit_amount": 4000,
"discount": 1000,
"tax_rate_bps": 1800,
"amount": 3000,
"tax": 540
}
],
"payment_link": "lnk_01j9xq2mt7c4vwd8hr5n",
"payment_url": "https://pay.payiz.app/l/fac-2026-0045-k3f8",
"payment": null,
"due_date": 1792594892,
"finalized_at": 1790002892,
"sent_at": 1790002893,
"paid_at": null,
"canceled_at": null,
"cancellation_reason": null,
"created": 1790002092,
"livemode": false
}Ce qu’on reçoit
201 · un objet invoice
object« invoice »Le genre de l’objet rendu : il ne change jamais.
idtexteUn identifiant préfixé « fac_ », par exemple fac_01j9xp6vb2n4rtw8kd3m.
numbertexte ou nullSon numéro, donné à l’émission et jamais avant : un brouillon n’en a pas.
customertexteLe client facturé.
customer_nametexteSon nom.
customer_emailtexte ou nullL’adresse où la facture part.
customer_phonetexte ou nullSon numéro, masqué.
status« draft » · « open » · « paid » · « canceled »« draft » : se compose encore ; « open » : émise, elle attend d’être payée ; « paid » : son lien a encaissé ; « canceled » : son lien n’encaisse plus.
overduevrai ou fauxL’échéance est passée et rien n’est payé. Ce n’est pas un statut de plus.
currencytexteLe code ISO 4217, en majuscules.
subtotalentierHors taxe, remises déduites.
total_discountentierLes remises de toutes les lignes.
total_taxentierLa taxe de toutes les lignes.
totalentierCe que le client paie : le lien encaisse celui-là.
fees_paid_by« merchant » · « customer »Qui porte la commission sur le paiement de la facture.
template« classic » · « banner » · « detailed » · « ticket » ou nullLe dessin voulu pour celle-ci ; null : celui de la boutique, figé à l’émission.
notetexte ou nullCe que la facture dit au client, sous les lignes.
linesliste de objetSes lignes, dans l’ordre.
payment_linktexte ou nullLe lien de paiement né à l’émission : c’est lui qui la règle.
payment_urltexte ou nullL’adresse où le client paie, celle que l’e-mail et le PDF portent.
paymenttexte ou nullLe paiement qui l’a réglée.
due_dateentier ou nullL’échéance.
finalized_atentier ou nullQuand elle a été émise.
sent_atentier ou nullQuand elle est partie chez le client par e-mail. Émise n’est pas envoyée : null tant qu’elle ne l’est pas.
paid_atentier ou nullDes secondes depuis 1970, ou null.
canceled_atentier ou nullDes secondes depuis 1970, ou null.
cancellation_reasontexte ou nullLe motif de l’annulation.
createdentier ou nullDes secondes depuis 1970, ou null.
livemodevrai ou fauxFaux en mode test : aucun argent ne circule.
object« invoice »Le genre de l’objet rendu : il ne change jamais.
idtexteUn identifiant préfixé « fac_ », par exemple fac_01j9xp6vb2n4rtw8kd3m.
numbertexte ou nullSon numéro, donné à l’émission et jamais avant : un brouillon n’en a pas.
customertexteLe client facturé.
customer_nametexteSon nom.
customer_emailtexte ou nullL’adresse où la facture part.
customer_phonetexte ou nullSon numéro, masqué.
status« draft » · « open » · « paid » · « canceled »« draft » : se compose encore ; « open » : émise, elle attend d’être payée ; « paid » : son lien a encaissé ; « canceled » : son lien n’encaisse plus.
overduevrai ou fauxL’échéance est passée et rien n’est payé. Ce n’est pas un statut de plus.
currencytexteLe code ISO 4217, en majuscules.
subtotalentierHors taxe, remises déduites.
total_discountentierLes remises de toutes les lignes.
total_taxentierLa taxe de toutes les lignes.
totalentierCe que le client paie : le lien encaisse celui-là.
fees_paid_by« merchant » · « customer »Qui porte la commission sur le paiement de la facture.
template« classic » · « banner » · « detailed » · « ticket » ou nullLe dessin voulu pour celle-ci ; null : celui de la boutique, figé à l’émission.
notetexte ou nullCe que la facture dit au client, sous les lignes.
linesliste de objetSes lignes, dans l’ordre.
payment_linktexte ou nullLe lien de paiement né à l’émission : c’est lui qui la règle.
payment_urltexte ou nullL’adresse où le client paie, celle que l’e-mail et le PDF portent.
paymenttexte ou nullLe paiement qui l’a réglée.
due_dateentier ou nullL’échéance.
finalized_atentier ou nullQuand elle a été émise.
sent_atentier ou nullQuand elle est partie chez le client par e-mail. Émise n’est pas envoyée : null tant qu’elle ne l’est pas.
paid_atentier ou nullDes secondes depuis 1970, ou null.
canceled_atentier ou nullDes secondes depuis 1970, ou null.
cancellation_reasontexte ou nullLe motif de l’annulation.
createdentier ou nullDes secondes depuis 1970, ou null.
livemodevrai ou fauxFaux en mode test : aucun argent ne circule.
© 2026 PayizUne question ? L’aide est dans le rond, en bas à droite.