Argent

Le journal de votre solde

GEThttps://tupay.apps.lepetittahitien.dev/api/v1/balance-transactions

Une ligne par mouvement : paiement, remboursement, et — à mesure qu'ils arriveront — virement et litige.

Chaque écriture porte grossXpf, feeXpf et netXpf. Le net suffirait à additionner ; les trois permettent d'expliquer.

### Le journal s'additionne

La somme des netXpf de toutes vos écritures est exactement votre solde. Celles dont availableAt est passé forment available, les autres pending.

### Ce que vous ne pouvez pas faire

Ni créer, ni modifier, ni supprimer une écriture. Il n'existe aucune route pour cela, et la base refuse de son côté : une écriture comptable est immuable.

Une correction s'écrit en ajustement — une ligne de plus, qui laisse la première visible. C'est ce que fait une comptabilité.

### Ce qui est figé sur chaque ligne

tgcRate et le couple feeBps / feeFixedXpf sont copiés au moment de l'écriture. Changer de régime de TGC ou renégocier votre tarif ne réécrit pas votre passé.

Paramètres de requête

typechaîne· requêtefacultatif
valeurs : payment, refund, fee, payout, dispute, adjustment
N'obtenir qu'un type de mouvement.
availablebooléen· requêtefacultatif
true pour ce qui est encaissable, false pour ce qui attend. La bascule est une comparaison de dates, pas un statut : rien n'a besoin de tourner pour qu'elle ait lieu.
limitentier· requêtefacultatif
minimum 1maximum 100défaut 25
Nombre d'éléments par page, entre 1 et 100. Vaut 25 par défaut sur toutes les collections.
Une valeur hors bornes est refusée par un 400 validation_error, jamais rabattue en silence sur 100.
starting_afterchaîne· requêtefacultatif
exemple 8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4
Curseur. Ne rend que les éléments situés APRÈS celui-ci dans l'ordre de parcours, donc plus anciens. L'élément désigné n'est jamais inclus dans la page.
C'est le paramètre du parcours normal : lisez une page, reprenez avec l'identifiant de son dernier élément.
Ne se combine ni avec ending_before, ni avec offset.
ending_beforechaîne· requêtefacultatif
exemple 8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4
Curseur inverse. Ne rend que les éléments situés AVANT celui-ci dans l'ordre de parcours, donc plus récents. L'élément désigné n'est jamais inclus dans la page.
Sous ce paramètre, has_more parle de ce qui reste avant la page, pas après.
Ne se combine ni avec starting_after, ni avec offset.
offsetentier· requêtefacultatif
minimum 0défaut 0
Déprécié, remplacé par starting_after. Reste accepté au minimum douze mois, avec exactement le comportement qu'il a toujours eu.
Pourquoi il est déprécié : un décalage nomme une POSITION dans un classement qui bouge. Dès qu'une ligne naît pendant votre parcours, tout ce qui suit glisse d'un cran, et vous sautez un élément sans rien voir. Un curseur nomme une LIGNE, et ne glisse pas.
Il n'est pas traduit en curseur : un décalage n'a pas d'équivalent en curseur, et prétendre le contraire vous rendrait une position instable rebaptisée.
Ne se combine ni avec starting_after, ni avec ending_before.
expand[]liste· requêtefacultatif
Développe une référence : le champ porte l'objet complet au lieu de son seul identifiant, qui reste servi. Répétez le paramètre pour plusieurs chemins.
Chemins acceptés : payment_method → customer ; payment_link → price ; price → product ; setup_intent → customer, payment_method ; transaction → payment_method ; transaction → payment_link, customer ; refund → transaction, transaction.payment_link, transaction.customer ; webhook_delivery → event. Un chemin inconnu vaut 400, en énumérant les chemins acceptés.
Profondeur maximale : 2. Au delà, 400 : un expand sans borne est une attaque par amplification.

Exemple d'appel

cURL

curl -X GET 'https://tupay.apps.lepetittahitien.dev/api/v1/balance-transactions' \
  -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/balance-transactions', {
  method: 'GET',
  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/balance-transactions';

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
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

Le journal, page par page

- dataliste· de objetfacultatif
  - 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.
- hasMorebooléenfacultatif

400application/json

Requête invalide

Code machine validation_error

Un champ du corps ne respecte pas son contrat (422).

{
  "error": "validation_error",
  "type": "invalid_request",
  "message": "Le montant minimum est de 100 XPF.",
  "code": 422
}

Code machine bad_request
Corps absent ou illisible, paramètre de requête hors bornes (400).
```
{
  "error": "bad_request",
  "type": "invalid_request",
  "message": "Corps JSON invalide.",
  "code": 400
}
```
Langage : json

Code machine invalid_cursor

Curseur de pagination qui ne se résout pas (400).

{
  "error": "invalid_cursor",
  "type": "invalid_request",
  "message": "Le curseur « starting_after » ne désigne aucun élément de cette collection : « 8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4 ». Reprenez le parcours depuis le début.",
  "code": 400
}

Code machine missing_idempotency_key

En-tête Idempotency-Key absent sur une opération qui l'exige (400).

{
  "error": "missing_idempotency_key",
  "type": "invalid_request",
  "message": "Header Idempotency-Key obligatoire.",
  "code": 400
}

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

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