Objets

Metadata

Objet de type object, sans champ nommé.

Transaction

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours transaction
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• amountXpfentierfacultatif
• amountEurCentsentierfacultatif

  Centimes EUR, pour réconciliation avec le prestataire bancaire.

• currencychaînefacultatif
  toujours XPF
• statuschaînefacultatif
  valeurs : pending, processing, succeeded, failed, refunded
• paymentIntentIdchaînefacultatif
• customerIdchaîne ou `null`facultatif
  format uuid

  Client rattaché, null pour un encaissement de passage. Développable : expand[]=customer.

• paymentMethodIdchaîne ou `null`facultatif
  format uuid

  Carte enregistrée débitée, null si le porteur a saisi la sienne. Développable : expand[]=payment_method.

• offSessionbooléenfacultatif

  Le porteur n'était pas devant son écran.

• failureCodechaîne ou `null`facultatif
  valeurs : card_declined, expired_card, incorrect_cvc, insufficient_funds, processing_error, authentication_required, null

  Sur un échec : la raison, en code machine stable. authentication_required n'est pas un refus.

• failureMessagechaîne ou `null`facultatif

  La même raison, en français, montrable au marchand.

• paymentLinkIdchaîne ou `null`facultatif
  format uuid
• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• refundedAmountXpfentierfacultatif

  Cumul remboursé. C'est ce champ qui fait foi, pas status : un remboursement partiel laisse status à succeeded.

• refundedAtchaîne ou `null`facultatif
  format date-time
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

PaymentLink

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours payment_link
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• amountXpfentierfacultatif
• currencychaînefacultatif
  toujours XPF
• descriptionchaînefacultatif
• slugchaînefacultatif
• urlchaînefacultatif

  URL publique à transmettre au client.

• returnUrlchaîne ou `null`facultatif
  format uri
• priceIdchaîne ou `null`facultatif
  format uuid

  Tarif dont ce lien hérite, null pour un montant libre. Développable — expand[]=price. Le montant reste servi dans amountXpf : un client qui le lit déjà n'a rien à changer.

• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• activebooléenfacultatif
• livemodebooléenfacultatif

  Un lien de test n'est pas payable. La page affiche un bandeau.

• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

Customer

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours customer
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• emailchaîne ou `null`facultatif
  format email
• namechaîne ou `null`facultatif
• phonechaîne ou `null`facultatif
• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• deletedbooléenfacultatif

  Toujours présent, y compris à false. Un client supprimé reste lisible et garde ses données : seule la fiche est retirée de la liste et fermée à la modification.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

PaymentMethod

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours payment_method
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• customerIdchaînefacultatif
  format uuid

  Client rattaché. Développable — expand[]=customer.

• brandchaînefacultatif
  exemple visa

  Marque, telle que le prestataire la nomme.

• last4chaînefacultatif
  motif ^[0-9]{4}$exemple 4242

  Les quatre derniers chiffres. Jamais plus.

• expMonthentierfacultatif
  minimum 1maximum 12
• expYearentierfacultatif
  exemple 2034
• defaultbooléenfacultatif

  Utilisé quand un paiement ne précise aucun moyen. Toujours présent, y compris à false.

• detachedbooléenfacultatif

  Vrai après DELETE. Le moyen n'est plus utilisable, mais reste lisible et garde ses attributs d'affichage.

• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

SetupIntent

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours setup_intent
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• customerIdchaînefacultatif
  format uuid

  Développable — expand[]=customer.

• statuschaînefacultatif
  valeurs : pending, succeeded, failed, canceled
• paymentMethodIdchaîne ou `null`facultatif
  format uuid

  Le moyen créé quand l'enregistrement aboutit, null avant. Développable — expand[]=payment_method.

• failureCodechaîne ou `null`facultatif
  valeurs : card_declined, expired_card, incorrect_cvc, insufficient_funds, processing_error, authentication_required, null

  Code machine STABLE. authentication_required n'est pas un refus : le porteur doit valider son authentification forte, ramenez-le devant son écran.

• failureMessagechaîne ou `null`facultatif

  Phrase française, montrable telle quelle au client final.

• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

Product

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours product
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• namechaînefacultatif
  exemple Sortie lagon
• descriptionchaîne ou `null`facultatif
• activebooléenfacultatif

  Un article désactivé n'apparaît plus dans les nouvelles ventes, mais ses tarifs existants continuent de fonctionner. Réversible — ce n'est pas une suppression.

• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

CheckoutSession

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours checkout_session
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• statuschaînefacultatif
  valeurs : open, complete, expired

  open tant qu'elle est payable, complete une fois l'argent reçu, expired passé l'échéance.

  Une session ne quitte jamais complete. Elle peut en revanche passer d'expired à complete : un paiement lancé avant l'échéance et confirmé après elle a bel et bien eu lieu, et c'est l'argent qui tranche.

• urlchaînefacultatif

  La page hébergée par Tupay. C'est là qu'on envoie le client.

• amountXpfentierfacultatif

  Total figé, somme des lignes. Entier XPF — le franc pacifique n'a pas de centimes.

• currencychaînefacultatif
  toujours XPF
• lineItemsliste· de objetfacultatif

  Ce que la page affiche, tel qu'il a été figé.

  • priceIdchaîne ou `null`facultatif
    format uuid

    null pour une ligne à montant libre.

  • descriptionchaînefacultatif
  • unitAmountXpfentierfacultatif
  • quantityentierfacultatif
  • amountXpfentierfacultatif

    unitAmountXpf × quantity.

• successUrlchaînefacultatif
• cancelUrlchaîne ou `null`facultatif
• customerIdchaîne ou `null`facultatif
  format uuid

  Développable — expand[]=customer.

• customerEmailchaîne ou `null`facultatif
  format email
• customerMatchchaîne ou `null`facultatif
  valeurs : provided, created, unique, ambiguous, null

  Comment la fiche a été obtenue au règlement. null tant que la session n'est pas réglée, ou s'il n'y avait rien à rapprocher.

  | Valeur | Ce qui s'est passé | |---|---| | provided | vous aviez fourni customer | | created | l'email était inconnu, une fiche a été créée | | unique | une seule fiche vivante portait cet email | | ambiguous | plusieurs la portaient — une fiche NEUVE a été créée |

  ambiguous est le seul cas qui demande une action de votre part. Nous ne rattachons jamais « à la plus récente » : cela ferait entrer l'achat d'une personne dans l'historique d'une autre.

• transactionIdchaîne ou `null`facultatif
  format uuid

  Le paiement en cours tant que la session est open — il en interdit un second — puis celui qui l'a réglée. Développable — expand[]=transaction.

• expiresAtentierfacultatif

  Secondes Unix. Entre 30 minutes et 24 heures après created.

• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

Receipt

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours receipt
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• statuschaînefacultatif
  valeurs : pending, succeeded, failed, exhausted

  exhausted = les sept tentatives sont épuisées, ou le fournisseur a refusé définitivement (adresse inexistante). Rien ne repartira sans POST /receipts/{id}/resend.

• emailchaînefacultatif
  format email

  L'adresse figée au moment du paiement. Corriger ou supprimer la fiche client ensuite ne la change pas : le reçu est parti là où votre client l'attendait.

• transactionIdchaînefacultatif
  format uuid

  Développable — expand[]=transaction.

• attemptsentierfacultatif
• nextRetryAtentier ou `null`facultatif

  Secondes Unix. null quand plus rien n'est prévu.

• sentAtentier ou `null`facultatif

  Secondes Unix.

• providerchaîne ou `null`facultatif

  Qui a traité l'envoi. resend = parti. `journal` = consigné, pas expédié — un environnement sans email configuré, ce qui n'arrive pas en production.

• lastErrorchaîne ou `null`facultatif
• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

Subscription

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours subscription
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• statuschaînefacultatif
  valeurs : active, paused, past_due, canceled

  past_due : le client n'a pas payé et il n'est pas coupé. Nous ne résilions pas à votre place — la décision vous appartient.

• customerIdchaînefacultatif
  format uuid

  Développable — expand[]=customer.

• priceIdchaînefacultatif
  format uuid

  Développable — expand[]=price.

• paymentMethodIdchaînefacultatif
  format uuid

  La carte retenue à la souscription. Non développable : elle porte les quatre derniers chiffres d'une carte, et une liste d'abonnements n'a pas à les faire défiler. Lisez-la par GET /payment-methods/{id}.

• cancelAtPeriodEndbooléenfacultatif

  Annulation programmée : le service court jusqu'à currentPeriodEnd, puis l'abonnement se ferme.

  Distincte de canceledAt, qui date la cessation effective. Sur un abonnement canceled, ce champ dit comment il s'est terminé : true = comme prévu, false = coupé net.

• canceledAtentier ou `null`facultatif

  Secondes Unix. null tant que l'abonnement n'a pas cessé.

• currentPeriodStartentierfacultatif

  Secondes Unix.

• currentPeriodEndentierfacultatif

  Secondes Unix. Fin de la période courante, donc la prochaine échéance. Il n'y a pas de second champ pour cet instant : deux champs pour une même date finiraient par diverger.

• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

BalanceTransaction

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours balance_transaction
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• sequenceentierfacultatif

  Numéro séquentiel par compte, par mode et par année, sans rupture. Une ligne manquante laisse un trou visible.

• typechaînefacultatif
  valeurs : payment, refund, fee, payout, dispute, adjustment
• transactionIdchaîne ou `null`facultatif
  format uuid

  Le paiement à l'origine du mouvement. Développable — expand[]=transaction.

• refundIdchaîne ou `null`facultatif
  format uuid

  Développable — expand[]=refund.

• grossXpfentierfacultatif

  Ce que le client a payé, TTC. Négatif sur un remboursement : le journal s'additionne sans cas particulier.

• feeXpfentierfacultatif

  Notre commission. Zéro sur un remboursement — elle n'est pas rendue, et celle du paiement d'origine reste acquise.

• netXpfentierfacultatif

  grossXpf − feeXpf. C'est lui qui rejoint votre solde.

• tgcXpfentierfacultatif

  La TGC transportée par ce mouvement, de même signe que le brut. Indicative : calculée au taux déclaré sur votre compte.

• tgcRatechaînefacultatif
  valeurs : exempt, 5, 10, 16

  Le taux figé au moment de l'écriture.

• tgcLabelchaînefacultatif

  « TGC 10 % incluse : 4 091 XPF », ou l'exonération.

• feeBpsentierfacultatif

  Le barème appliqué, figé. 250 = 2,5 %.

• feeFixedXpfentierfacultatif

  Part fixe du barème, figée.

• availableAtentierfacultatif

  Secondes Unix : quand ce montant bascule en available. Figée à l'écriture, jamais recalculée.

• currencychaînefacultatif
  toujours XPF
• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

Balance

• objectchaînefacultatif
  toujours balance
• availableobjetfacultatif

  Encaissable dès maintenant.

  • amountXpfentierfacultatif

    Ce qui vous revient, commission déduite, en francs entiers.

  • tgcXpfentierfacultatif

    La TGC contenue dans amountXpf. Indicatif : calculé au taux déclaré sur votre compte.

  • netOfTgcXpfentierfacultatif

    amountXpf − tgcXpf — ce qui reste une fois la taxe réservée.

  • countentierfacultatif

    Nombre d'écritures dans cette part.

• pendingobjetfacultatif

  Pas encore encaissable. nextAvailableAt dit quand la plus proche de ces écritures bascule.

  • amountXpfentierfacultatif

    Ce qui vous revient, commission déduite, en francs entiers.

  • tgcXpfentierfacultatif

    La TGC contenue dans amountXpf. Indicatif : calculé au taux déclaré sur votre compte.

  • netOfTgcXpfentierfacultatif

    amountXpf − tgcXpf — ce qui reste une fois la taxe réservée.

  • countentierfacultatif

    Nombre d'écritures dans cette part.

• nextAvailableAtentier ou `null`facultatif

  Secondes Unix : quand la plus proche écriture en attente bascule. null quand rien n'est en attente.

• currencychaînefacultatif
  toujours XPF
• livemodebooléenfacultatif

PartDeSolde

• amountXpfentierfacultatif

  Ce qui vous revient, commission déduite, en francs entiers.

• tgcXpfentierfacultatif

  La TGC contenue dans amountXpf. Indicatif : calculé au taux déclaré sur votre compte.

• netOfTgcXpfentierfacultatif

  amountXpf − tgcXpf — ce qui reste une fois la taxe réservée.

• countentierfacultatif

  Nombre d'écritures dans cette part.

Invoice

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours invoice
• numberchaînefacultatif
  exemple FAC-2026-000004

  Le numéro comptable : séquentiel, chronologique et sans rupture, par compte et par année. C'est lui qu'on cite à un comptable ; id ne désigne la facture que dans l'API.

  Attribué par Tupay, jamais modifiable. Le mode test a son propre compteur et son propre préfixe — TEST-2026-000004 — pour qu'une intégration en cours ne creuse pas de trou dans votre séquence réelle.

• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• statuschaînefacultatif
  valeurs : open, paid, past_due, void
• subscriptionIdchaînefacultatif
  format uuid

  Développable — expand[]=subscription.

• customerIdchaînefacultatif
  format uuid

  Développable — expand[]=customer.

• transactionIdchaîne ou `null`facultatif
  format uuid

  Le prélèvement tenté. null tant qu'aucune tentative n'a eu lieu. Développable — expand[]=transaction.

• amountXpfentierfacultatif

  TTC, entier XPF. htXpf + tgcXpf vaut exactement cette valeur — la base le vérifie, quel que soit le code qui écrit.

• htXpfentierfacultatif

  Base hors taxe.

• tgcXpfentierfacultatif

  Taxe comprise dans le TTC, jamais ajoutée. Sur 6 000 XPF à 5 % elle vaut 286, et non 300.

• tgcRatechaînefacultatif
  valeurs : exempt, 5, 10, 16

  Le taux figé à l'émission, pas celui de votre compte aujourd'hui. C'est ce qui rend une facture relisible des années plus tard.

• tgcLabelchaînefacultatif

  « TGC 5 % incluse : 286 XPF », ou l'exonération.

• currencychaînefacultatif
  toujours XPF
• periodStartentierfacultatif

  Secondes Unix.

• periodEndentierfacultatif

  Secondes Unix.

• linesliste· de objetfacultatif

  Rendues d'office — une facture sans ses lignes n'en est pas une.

  • descriptionchaînefacultatif
  • quantityentierfacultatif
  • unitAmountXpfentierfacultatif
  • amountXpfentierfacultatif

    TTC.

  • htXpfentierfacultatif
  • tgcXpfentierfacultatif
• attemptsentierfacultatif

  Tentatives de prélèvement déjà faites, celle de l'émission comprise.

• nextAttemptAtentier ou `null`facultatif

  Prochaine relance prévue, en secondes Unix. null = plus rien : la facture est réglée, ou le barème est épuisé.

• attemptHistoryliste· de objetfacultatif

  Le journal des tentatives. Rendu seulement sur GET /invoices/{id} : cinq lignes par facture, personne ne lit cent journaux d'un coup.

  Un compteur dit combien ; ce journal dit quand et pourquoi.

  • attemptentierfacultatif
  • succeededbooléenfacultatif
  • transactionIdchaîne ou `null`facultatif
    format uuid
  • failureCodechaîne ou `null`facultatif

    Code machine, du catalogue d'erreurs.

  • failureMessagechaîne ou `null`facultatif

    Message français, à montrer au marchand.

  • attemptedAtentierfacultatif

    Secondes Unix.

• paidAtentier ou `null`facultatif

  Secondes Unix. null tant que la facture n'est pas réglée.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

Price

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours price
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• productIdchaînefacultatif
  format uuid

  Développable — expand[]=product.

• amountXpfentierfacultatif

  Entier XPF. Le franc pacifique n'a pas de centimes.

• currencychaînefacultatif
  toujours XPF
• recurringobjet ou `null`facultatif

  null pour un tarif ponctuel.

  • intervalchaînefacultatif
    valeurs : day, week, month, year
  • intervalCountentierfacultatif
• nicknamechaîne ou `null`facultatif
• activebooléenfacultatif

  Un tarif désactivé n'est plus proposé, mais reste consultable et continue d'honorer les liens qui le référencent.

• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time

Refund

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours refund
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• transactionIdchaînefacultatif
  format uuid
• amountXpfentierfacultatif
• currencychaînefacultatif
  toujours XPF
• statuschaînefacultatif
  valeurs : pending, succeeded, failed
• reasonchaîne ou `null`facultatif
• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

WebhookEndpoint

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours webhook_endpoint
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• urlchaînefacultatif
  format uri
• descriptionchaîne ou `null`facultatif
• enabledEventsliste· de chaînefacultatif
• statuschaînefacultatif
  valeurs : enabled, disabled
• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time
• disabledAtchaîne ou `null`facultatif
  format date-time

WebhookDelivery

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours webhook_delivery
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• eventIdchaînefacultatif
• eventTypechaînefacultatif
• statuschaînefacultatif
  valeurs : pending, succeeded, failed, exhausted
• attemptsentierfacultatif
• responseStatusentier ou `null`facultatif
• responseBodychaîne ou `null`facultatif
• lastErrorchaîne ou `null`facultatif
• nextRetryAtchaîne ou `null`facultatif
  format date-time
• deliveredAtchaîne ou `null`facultatif
  format date-time
• livemodebooléenfacultatif

  Le mode de l'endpoint destinataire — une livraison n'en porte pas elle-même. Sans lui, vous ne pouviez pas savoir si une livraison affichée était réelle ou de test sans remonter à son endpoint.

• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

Merchant

• idchaînefacultatif
  format uuid
• objectchaînefacultatif
  toujours merchant
• createdentierfacultatif

  Secondes Unix. Même instant que createdAt.

• emailchaînefacultatif
  format email
• namechaînefacultatif
• kybStatuschaînefacultatif
  valeurs : pending, validated, rejected
• ibanXpfchaîne ou `null`facultatif
• tgcRatechaînefacultatif
  valeurs : exempt, 5, 10, 16
• metadataobjetfacultatif
  au plus 50 clés

  Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

  ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

  Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

  Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

  À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

  Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

• livemodebooléenfacultatif
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• updatedAtchaînefacultatif
  format date-time
• kyb_statuschaînefacultatif
  valeurs : pending, validated, rejected

  Doublon de kybStatus. Servi au minimum douze mois, puis retiré par une version datée.

• iban_xpfchaîne ou `null`facultatif

  Doublon de ibanXpf. Lisez ibanXpf.

• tgc_ratechaînefacultatif
  valeurs : exempt, 5, 10, 16

  Doublon de tgcRate. Lisez tgcRate.

• created_atchaînefacultatif
  format date-time

  Doublon de createdAt. Lisez createdAt, ou created.

• updated_atchaînefacultatif
  format date-time

  Doublon de updatedAt. Lisez updatedAt.

Event

• idchaînefacultatif
  exemple evt_9f8c1a2b3d4e5f60
• objectchaînefacultatif
  valeurs : event
• createdentierfacultatif
  exemple 1767225600

  Secondes Unix. Même instant que createdAt.

• typechaînefacultatif
  exemple payment.succeeded
• createdAtchaînefacultatif
  format date-time

  Doublon de created. Lisez created.

• livemodebooléenfacultatif
• dataobjetfacultatif
  • objectobjetfacultatif

    Forme identique dans les réponses REST et dans data.object des webhooks : un seul modèle à écrire côté intégrateur.

    • idchaînefacultatif
      format uuid
    • objectchaînefacultatif
      toujours transaction
    • createdentierfacultatif

      Secondes Unix. Même instant que createdAt.

    • amountXpfentierfacultatif
    • amountEurCentsentierfacultatif

      Centimes EUR, pour réconciliation avec le prestataire bancaire.

    • currencychaînefacultatif
      toujours XPF
    • statuschaînefacultatif
      valeurs : pending, processing, succeeded, failed, refunded
    • paymentIntentIdchaînefacultatif
    • customerIdchaîne ou `null`facultatif
      format uuid

      Client rattaché, null pour un encaissement de passage. Développable : expand[]=customer.

    • paymentMethodIdchaîne ou `null`facultatif
      format uuid

      Carte enregistrée débitée, null si le porteur a saisi la sienne. Développable : expand[]=payment_method.

    • offSessionbooléenfacultatif

      Le porteur n'était pas devant son écran.

    • failureCodechaîne ou `null`facultatif
      valeurs : card_declined, expired_card, incorrect_cvc, insufficient_funds, processing_error, authentication_required, null

      Sur un échec : la raison, en code machine stable. authentication_required n'est pas un refus.

    • failureMessagechaîne ou `null`facultatif

      La même raison, en français, montrable au marchand.

    • paymentLinkIdchaîne ou `null`facultatif
      format uuid
    • metadataobjetfacultatif
      au plus 50 clés

      Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

      ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

      Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

      Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

      À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

      Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

    • livemodebooléenfacultatif
    • refundedAmountXpfentierfacultatif

      Cumul remboursé. C'est ce champ qui fait foi, pas status : un remboursement partiel laisse status à succeeded.

    • refundedAtchaîne ou `null`facultatif
      format date-time
    • createdAtchaînefacultatif
      format date-time

      Doublon de created. Lisez created.

    • updatedAtchaînefacultatif
      format date-time

WebhookEvent

• idchaînefacultatif

  Identifiant d'événement. Dédupliquez dessus.

• objectchaînefacultatif
  toujours event
• typechaînefacultatif
  valeurs : payment.succeeded, payment.failed, payment.processing, payment.refunded
• apiVersionchaînefacultatif
  toujours 2026-01-01
• createdentierfacultatif

  Horodatage Unix en secondes.

• livemodebooléenfacultatif
• dataobjetfacultatif
  • objectobjetfacultatif

    Forme identique dans les réponses REST et dans data.object des webhooks : un seul modèle à écrire côté intégrateur.

    • idchaînefacultatif
      format uuid
    • objectchaînefacultatif
      toujours transaction
    • createdentierfacultatif

      Secondes Unix. Même instant que createdAt.

    • amountXpfentierfacultatif
    • amountEurCentsentierfacultatif

      Centimes EUR, pour réconciliation avec le prestataire bancaire.

    • currencychaînefacultatif
      toujours XPF
    • statuschaînefacultatif
      valeurs : pending, processing, succeeded, failed, refunded
    • paymentIntentIdchaînefacultatif
    • customerIdchaîne ou `null`facultatif
      format uuid

      Client rattaché, null pour un encaissement de passage. Développable : expand[]=customer.

    • paymentMethodIdchaîne ou `null`facultatif
      format uuid

      Carte enregistrée débitée, null si le porteur a saisi la sienne. Développable : expand[]=payment_method.

    • offSessionbooléenfacultatif

      Le porteur n'était pas devant son écran.

    • failureCodechaîne ou `null`facultatif
      valeurs : card_declined, expired_card, incorrect_cvc, insufficient_funds, processing_error, authentication_required, null

      Sur un échec : la raison, en code machine stable. authentication_required n'est pas un refus.

    • failureMessagechaîne ou `null`facultatif

      La même raison, en français, montrable au marchand.

    • paymentLinkIdchaîne ou `null`facultatif
      format uuid
    • metadataobjetfacultatif
      au plus 50 clés

      Clés libres (longueur maximale 40), valeurs de type chaîne (longueur maximale 500).

      ⚠️ Une valeur qui ressemble à un numéro de carte bancaire est REFUSÉE, sur toutes les ressources : Tupay n'en stocke jamais, y compris ici. Ce refus protège votre conformité PCI-DSS autant que la nôtre. Si c'est une référence interne numérique, préfixez-la (« cmd-… ») pour lever l'ambiguïté.

      Vos propres clés et valeurs, attachées à l'objet et relisibles avec lui. De quoi relier une ressource Tupay à votre système sans tenir de table de correspondance.

      Bornes : 50 clés au plus, 40 caractères par clé, 500 par valeur. Elles portent sur le RÉSULTAT de la fusion, pas sur ce que vous envoyez : ajouter 5 clés à un objet qui en compte 48 est refusé.

      À la modification, les clés fournies remplacent les anciennes et les autres survivent. Une clé à null est supprimée. Un objet vide ne change rien, et metadata: null efface tout.

      Ce n'est pas un espace de stockage : les valeurs ne sont ni indexées ni cherchables, et n'ont aucun effet sur le traitement.

    • livemodebooléenfacultatif
    • refundedAmountXpfentierfacultatif

      Cumul remboursé. C'est ce champ qui fait foi, pas status : un remboursement partiel laisse status à succeeded.

    • refundedAtchaîne ou `null`facultatif
      format date-time
    • createdAtchaînefacultatif
      format date-time

      Doublon de created. Lisez created.

    • updatedAtchaînefacultatif
      format date-time

Error

• errorchaînerequis

  Code machine stable, en snake_case anglais.

• typechaînerequis
  valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

  Classe de l'erreur, dans un ensemble fermé.

  invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

• messagechaînerequis

  Destiné à un humain, toujours en français.

• codeentierrequis

  Statut HTTP, repris dans le corps par commodité.