Terminal

Ouvrir un encaissement au comptoir

POSThttps://tupay.apps.lepetittahitien.dev/api/v1/terminal/checkout

Crée l'encaissement que l'application mobile présente ensuite au lecteur de carte, et la transaction Tupay correspondante.

Toujours en mode réel. Un encaissement au comptoir n'a pas de variante bac à sable : livemode vaut systématiquement true.

Session marchand obligatoire. Une clé tpk_… reçoit 401. merchantId doit être celui de la session, sinon 403.

Paramètres d’en-tête

Idempotency-Keychaîne· en-têterequis
exemple 9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13
Obligatoire sur cette opération. UUID v4 recommandé. Rejouer la même clé renvoie le résultat mémorisé sans réexécuter l'opération : un retry après timeout ne débite jamais deux fois.
La clé est cloisonnée par marchand : deux comptes peuvent employer la même chaîne sans jamais se voir.
Rejouer une clé avec un corps différent vaut 409 idempotency_key_reuse. Seuls l'ordre des clés JSON et l'espacement sont ignorés dans la comparaison. La méthode et le chemin font partie de l'empreinte : la même clé sur une autre opération est donc un corps différent.
Une seconde requête arrivant pendant que la première s'exécute attend au plus trois secondes, puis reçoit 409 idempotency_in_progress. Il faut alors retenter la même requête à l'identique.
Rétention : 24 heures. Passé ce délai la clé redevient libre, et la rejouer CRÉE une nouvelle ressource au lieu de rendre le corps mémorisé.

Corps de requête application/json · requis

amountXpfentierrequis
minimum 100maximum 10000000exemple 4500
merchantIdchaînerequis
format uuidexemple 2b9d7c14-6f3a-42e8-b05c-9a1e4d7f6c28
Doit être le marchand de la session en cours.
descriptionchaînefacultatif
longueur maximale 256
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.

Exemple d'appel

cURL

curl -X POST 'https://tupay.apps.lepetittahitien.dev/api/v1/terminal/checkout' \
  -H 'Cookie: authjs.session-token=votre-jeton-de-session' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13' \
  --data '{
  "amountXpf": 4500,
  "merchantId": "2b9d7c14-6f3a-42e8-b05c-9a1e4d7f6c28"
}'

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/terminal/checkout', {
  method: 'POST',
  headers: {
    Cookie: 'authjs.session-token=votre-jeton-de-session',
    'Content-Type': 'application/json',
    Accept: 'application/json',
    'Idempotency-Key': '9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13',
  },
  body: JSON.stringify({
    amountXpf: 4500,
    merchantId: '2b9d7c14-6f3a-42e8-b05c-9a1e4d7f6c28',
  }),
})

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/terminal/checkout';

$corps = json_encode([
    'amountXpf' => 4500,
    'merchantId' => '2b9d7c14-6f3a-42e8-b05c-9a1e4d7f6c28',
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Cookie: authjs.session-token=votre-jeton-de-session',
    'Content-Type: application/json',
    'Accept: application/json',
    'Idempotency-Key: 9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13',
]);
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);
curl_setopt($curl, CURLOPT_POSTFIELDS, $corps);

$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

Cookie de session authjs.session-token
Session marchand Auth.js (JWT en cookie, 7 jours). Le nom du cookie est __Secure-authjs.session-token en HTTPS.
Utilisée par l'application mobile de terminal. Une clé tpk_… ne fonctionne PAS sur ces routes : elle reçoit 401.

Réponses

201application/json

Encaissement ouvert

- checkoutIdchaînefacultatif
  Identifiant à passer au SDK du lecteur.
- transactionIdchaînefacultatif
  format uuid
  Identifiant Tupay, utilisé par les remboursements, les webhooks et l'export.
- amountXpfentierfacultatif
- amountEurCentsentierfacultatif

400application/json

missing_idempotency_key si l'en-tête Idempotency-Key manque, bad_request si le corps n'est pas du JSON valide.

Code machine missing_idempotency_key

En-tête Idempotency-Key absent.

{
  "error": "missing_idempotency_key",
  "type": "invalid_request",
  "message": "En-tête Idempotency-Key requis.",
  "code": 400
}

Code machine bad_request

Corps de requête illisible.

{
  "error": "bad_request",
  "type": "invalid_request",
  "message": "Corps JSON invalide.",
  "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é.

403application/json

Opération interdite dans ce contexte

Code machine forbidden

Identité valide, mais l'opération lui est refusée.

{
  "error": "forbidden",
  "type": "permission",
  "message": "Accès refusé.",
  "code": 403
}

- 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

État incompatible avec l'opération

Code machine conflict

L'état courant de la ressource interdit l'opération.

{
  "error": "conflict",
  "type": "conflict",
  "message": "Cette transaction est déjà intégralement remboursée.",
  "code": 409
}

Code machine idempotency_key_reuse

Clé déjà employée pour une AUTRE requête (409). Reprise : choisissez une nouvelle clé. Aucun des deux corps n'a été appliqué.

{
  "error": "idempotency_key_reuse",
  "type": "idempotency",
  "message": "Cette clé d’idempotence a déjà servi pour une requête différente. Choisissez-en une nouvelle : rejouer une clé ne vaut que pour la requête exacte qui l’a créée.",
  "code": 409
}

Code machine idempotency_in_progress
Une requête portant la même clé est encore en cours (409). Reprise : retentez la même requête à l'identique dans un instant. Aucune seconde ressource n'a été créée.
```
{
  "error": "idempotency_in_progress",
  "type": "idempotency",
  "message": "Une requête portant cette clé est encore en cours. Retentez le même appel, avec la même clé, dans un instant.",
  "code": 409
}
```
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é.

422application/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é.

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

500application/json

Le prestataire n'a pas ouvert l'encaissement (checkout_creation_failed)

Code machine checkout_creation_failed

Le prestataire n'a pas ouvert l'encaissement au comptoir.

{
  "error": "checkout_creation_failed",
  "type": "provider",
  "message": "Encaissement indisponible.",
  "code": 500
}

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