Sessions de paiement

Détail d'une session de paiement

GEThttps://tupay.apps.lepetittahitien.dev/api/v1/checkout-sessions/{id}

C'est ici que l'expiration est matérialisée : une session open dont l'échéance est passée est rendue expired, et l'est désormais pour tout le monde.

Aucune tâche périodique n'en est chargée — un travail planifié qui ne tourne pas laisserait des sessions payables au-delà de leur heure.

Paramètres de chemin

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

Paramètres de requête

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/checkout-sessions/8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4' \
  -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/checkout-sessions/8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4', {
  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/checkout-sessions/8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4';

$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

Session

- dataobjetfacultatif
  Une page de paiement hébergée. Le total est figé à la création et ne suit plus le catalogue.
  - idchaînefacultatif
    format uuid
  - objectchaînefacultatif
    toujours checkout_session
  - createdentierfacultatif
    Secondes Unix. Même instant que createdAt.
  - statuschaînefacultatif
    valeurs : open, complete, expired
    open tant qu'elle est payable, complete une fois l'argent reçu, expired passé l'échéance.
    Une session ne quitte jamais complete. Elle peut en revanche passer d'expired à complete : un paiement lancé avant l'échéance et confirmé après elle a bel et bien eu lieu, et c'est l'argent qui tranche.
  - urlchaînefacultatif
    La page hébergée par Tupay. C'est là qu'on envoie le client.
  - amountXpfentierfacultatif
    Total figé, somme des lignes. Entier XPF — le franc pacifique n'a pas de centimes.
  - currencychaînefacultatif
    toujours XPF
  - lineItemsliste· de objetfacultatif
    Ce que la page affiche, tel qu'il a été figé.
    - priceIdchaîne ou `null`facultatif
      format uuid
      null pour une ligne à montant libre.
    - descriptionchaînefacultatif
    - unitAmountXpfentierfacultatif
    - quantityentierfacultatif
    - amountXpfentierfacultatif
      unitAmountXpf × quantity.
  - successUrlchaînefacultatif
  - cancelUrlchaîne ou `null`facultatif
  - customerIdchaîne ou `null`facultatif
    format uuid
    Développable — expand[]=customer.
  - customerEmailchaîne ou `null`facultatif
    format email
  - customerMatchchaîne ou `null`facultatif
    valeurs : provided, created, unique, ambiguous, null
    Comment la fiche a été obtenue au règlement. null tant que la session n'est pas réglée, ou s'il n'y avait rien à rapprocher.
    | Valeur | Ce qui s'est passé | |---|---| | provided | vous aviez fourni customer | | created | l'email était inconnu, une fiche a été créée | | unique | une seule fiche vivante portait cet email | | ambiguous | plusieurs la portaient — une fiche NEUVE a été créée |
    ambiguous est le seul cas qui demande une action de votre part. Nous ne rattachons jamais « à la plus récente » : cela ferait entrer l'achat d'une personne dans l'historique d'une autre.
  - transactionIdchaîne ou `null`facultatif
    format uuid
    Le paiement en cours tant que la session est open — il en interdit un second — puis celui qui l'a réglée. Développable — expand[]=transaction.
  - expiresAtentierfacultatif
    Secondes Unix. Entre 30 minutes et 24 heures après created.
  - 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.
  - livemodebooléenfacultatif
  - createdAtchaînefacultatif
    format date-time
    Doublon de created. Lisez created.
  - updatedAtchaînefacultatif
    format date-time

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