Argent

Votre solde

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

Ce que vous avez, et ce qui arrive.

available est encaissable ; pending ne l'est pas encore. La différence est une date : chaque mouvement porte l'instant où il bascule, figé au moment où il est écrit. Rien ne le recalcule à l'affichage.

Le solde n'a ni identifiant ni date de création : c'est un état instantané, pas un objet stocké. Ce sont les écritures qui en ont.

### La TGC apparaît à part

Vos montants sont TTC. Un solde brut contiendrait donc la TGC que vous devez à la DICP, et que vous risqueriez de dépenser. tgcXpf vous dit combien, et netOfTgcXpf ce qu'il vous reste une fois cette taxe mise de côté.

⚠️ C'est une indication, pas une déclaration. Nous appliquons le taux déclaré sur votre compte. Si vous vendez à plusieurs taux, ce chiffre ne peut pas être exact — votre comptable, lui, le sera.

### Les frais sont déjà déduits

amountXpf est net de commission. Le détail — brut, frais, net — se lit sur chaque écriture.

⚠️ Tant qu'aucun acquéreur n'est branché, les délais de disponibilité sont ceux d'une estimation : J+2 ouvrés. La mécanique est réelle ; le calendrier sera celui du contrat.

Exemple d'appel

cURL

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

$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 solde, à l'instant de l'appel

- dataobjetfacultatif
  État instantané, pas une ressource stockée : ni id, ni created. Le solde est la somme de vos écritures au moment où vous le demandez.
  - 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

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