Bac à sable

Obtenir une clé de test sans inscription

POSThttps://tupay.apps.lepetittahitien.dev/api/v1/sandbox/keys

Délivre une clé tpk_test_ immédiatement : ni email, ni mot de passe, ni validation humaine. Le KYB vérifie l'identité de qui va encaisser de l'argent réel ; il n'a rien à vérifier sur un bac à sable où rien n'est encaissé.

La clé ne vaut qu'en mode test. Elle ne peut ni encaisser, ni créer une clé live, ni lire une donnée réelle. Le compte associé est purgé passé le délai annoncé par le champ ttlHours de la réponse.

Le nombre de clés délivrées est plafonné par adresse IP. Corps de requête vide.

L'en-tête Idempotency-Key est IGNORÉ ici. Cette opération n'est pas authentifiée : il n'y a pas de compte à qui rattacher la clé, donc pas de cloisonnement possible entre appelants. Une clé partagée par tous serait une fuite, pas une garantie.

Exemple d'appel

cURL

curl -X POST 'https://tupay.apps.lepetittahitien.dev/api/v1/sandbox/keys' \
  -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/sandbox/keys', {
  method: 'POST',
  headers: {
    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/sandbox/keys';

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

Sans authentification

Appelable sans clé API et sans session.

Réponses

201application/json

Clé de test délivrée

- dataobjetfacultatif
  - objectchaînefacultatif
    toujours sandbox_key
  - apiKeychaînefacultatif
    exemple tpk_test_4f2a9c8e1b6d0a35
    Valeur brute, renvoyée une seule fois : seul son SHA-256 est conservé.
  - merchantIdchaînefacultatif
    format uuid
    Exigé par POST /payments/intent.
  - livemodebooléenfacultatif
    toujours false
  - expiresAtchaînefacultatif
    format date-time
    Purge du compte de démonstration.
  - ttlHoursentierfacultatif
    exemple 24
  - quickstartobjetfacultatif
    Premiers appels à essayer, dans l'ordre.
    - documentationchaînefacultatif
    - creerUnLienchaînefacultatif
    - creerUnPaiementchaînefacultatif
    - forcerLIssuechaînefacultatif

429application/json

Deux causes distinctes, deux codes machine, à ne pas confondre :

- rate_limit_exceeded : vous appelez trop vite. Quelques secondes suffisent. - sandbox_quota_exceeded : le plafond de 10 clés par adresse IP sur 24 heures glissantes est atteint. Le corps porte alors reprendAt, l'instant exact où une nouvelle clé redeviendra disponible. Inutile de réessayer avant.

Code machine sandbox_quota_exceeded

Plafond de clés atteint pour cette adresse IP.

{
  "error": "sandbox_quota_exceeded",
  "type": "rate_limit",
  "message": "Plafond atteint : 10 clés de test par adresse IP sur 24 heures glissantes. La plus ancienne se libère le 2026-08-19T06:30:56.236Z. Créez un compte permanent pour ne plus dépendre de ce plafond.",
  "code": 429,
  "reprendAt": "2026-08-19T06:30:56.236Z"
}

Code machine rate_limit_exceeded

Appels trop rapprochés. Réessayez dans un instant.

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

- errorchaînerequis
  exemple sandbox_quota_exceeded
- messagechaînerequis
- codeentierrequis
  exemple 429
- reprendAtchaînefacultatif
  format date-timeexemple 2026-08-19T06:30:56.236Z
  Instant à partir duquel une nouvelle clé pourra être obtenue depuis cette adresse. Présent uniquement avec sandbox_quota_exceeded.

500application/json

Création du compte de démonstration échouée (server_error)

Code machine server_error
Le compte de démonstration n'a pas pu être créé.
```
{
  "error": "server_error",
  "type": "api",
  "message": "Erreur serveur.",
  "code": 500
}
```
Langage : json

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