Factures

Retenter le prélèvement d'une facture

POSThttps://tupay.apps.lepetittahitien.dev/api/v1/invoices/{id}/pay

Débite maintenant, sans attendre le prochain palier du barème de relance.

Utile quand votre client vient de corriger sa carte et que vous ne voulez pas lui faire attendre jusqu'à sept jours.

### Ce que la route ne fait pas

Elle ne remet pas le compteur à zéro. Une carte neuve ne mérite pas cinq essais de plus si elle échoue aussi — votre client verrait défiler dix refus sur son relevé.

### Le refus est rendu en 200

Un prélèvement refusé n'est pas une panne de l'API : c'est le résultat de la tentative. La réponse porte la facture à jour et un objet attempt qui dit ce qui s'est passé.

Une facture déjà réglée vaut 409 : la retenter débiterait votre client une seconde fois.

Paramètres de chemin

idchaîne· cheminrequis
format uuidexemple 8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4

Exemple d'appel

cURL

curl -X POST 'https://tupay.apps.lepetittahitien.dev/api/v1/invoices/8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4/pay' \
  -H 'Authorization: Bearer tpk_test_4f2a9c8e1b6d0a35' \
  -H 'Accept: application/json'

Node

// Le SDK tupay ne couvre pas encore cette route : on appelle
// l'API directement, avec le `fetch` natif de Node 18 ou plus.
const reponse = await fetch('https://tupay.apps.lepetittahitien.dev/api/v1/invoices/8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4/pay', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TUPAY_SECRET_KEY}`,
    Accept: 'application/json',
  },
})

if (!reponse.ok) {
  throw new Error(`Tupay a répondu ${reponse.status}`)
}

const resultat: unknown = await reponse.json()
console.log(resultat)

PHP

<?php

// Aucune dépendance : l'extension cURL suffit, et elle est activée par
// défaut sur la quasi-totalité des hébergements PHP.
// En contexte WordPress, préférez wp_remote_request() : cette API-là
// respecte les proxys, certificats et filtres de l'hébergement.

$url = 'https://tupay.apps.lepetittahitien.dev/api/v1/invoices/8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4/pay';

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer tpk_test_4f2a9c8e1b6d0a35',
    'Accept: application/json',
]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 10);
// Vérification TLS non négociable : sans elle, un intermédiaire pourrait
// se faire passer pour l'API et récolter votre clé secrète.
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);

$reponse = curl_exec($curl);
$statut = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$erreurReseau = curl_error($curl);
curl_close($curl);

if (false === $reponse) {
    throw new RuntimeException('Appel Tupay impossible : ' . $erreurReseau);
}

$donnees = json_decode($reponse, true);

if ($statut >= 400) {
    // Branchez vos traitements sur `error`, le code machine : il est
    // stable, là où le message est susceptible d'évoluer.
    throw new RuntimeException('Tupay a répondu ' . $statut . ' (' . $donnees['error'] . ')');
}

var_dump($donnees);

Les valeurs sont celles d'un compte de test : remplacez la clé et les identifiants par les vôtres.

Console d'essai

Exécuter un appel depuis cette page demande JavaScript. Le guide de prise en main délivre une clé de test et montre les mêmes appels sans JavaScript.

Authentification

Jeton porteur, en-tête Authorization
Authorization: Bearer tpk_live_… ou Authorization: Bearer tpk_test_…

Réponses

200application/json

Tentative effectuée, aboutie ou non

- dataobjetfacultatif
  Facture d'une échéance d'abonnement. Montants TTC, ventilation TGC figée à l'émission.
  - 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
  - attemptobjetfacultatif
    - succeededbooléenfacultatif
    - outcomechaînefacultatif
      valeurs : reglee, a_relancer, en_souffrance
    - failureMessagechaîne ou `null`facultatif

401application/json

Clé absente, invalide ou révoquée

Code machine unauthorized

Aucune identité valide n'a pu être établie.

{
  "error": "unauthorized",
  "type": "authentication",
  "message": "Authentification requise.",
  "code": 401
}

- 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é.

404application/json

Ressource inexistante, hors de votre périmètre, ou appartenant à l'AUTRE MODE. Nous renvoyons 404 plutôt que 403 pour ne pas confirmer l'existence de ce qui ne vous appartient pas.

Code machine not_found

Inexistante, ou appartenant à un autre marchand.

{
  "error": "not_found",
  "type": "not_found",
  "message": "Ressource introuvable.",
  "code": 404
}

- 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é.

409application/json

La facture est déjà réglée, ou annulée.

- 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é.

429application/json

100 req/min par marchand dépassées

Code machine rate_limit_exceeded

Plafond de requêtes atteint. Réessayez après une pause.

{
  "error": "rate_limit_exceeded",
  "type": "rate_limit",
  "message": "Trop de requêtes. Réessayez dans un instant.",
  "code": 429
}

- 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é.