Événements

Lister les événements émis

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

Les événements du marchand, du plus récent au plus ancien.

Ils existent indépendamment de leurs livraisons : un marchand sans endpoint de webhook garde quand même une trace complète de son activité.

Pagination par CURSEUR, pas par décalage. Un offset glisse dès qu'un événement naît pendant le parcours, on en saute alors silencieusement.

Le mode vient de la clé : une clé de test ne voit jamais les événements live, et réciproquement.

Paramètres de requête

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.
apreschaîne· requêtefacultatif
exemple evt_9f8c1a2b3d4e5f60
Déprécié, renommé starting_after. Alias strict : même comportement, même validation, deux noms. Reste accepté au minimum douze mois.
Ne se combine pas avec starting_after ni ending_before.
typechaîne· requêtefacultatif
valeurs : payment.succeeded, payment.failed, payment.processing, payment.refunded

Exemple d'appel

cURL

curl -X GET 'https://tupay.apps.lepetittahitien.dev/api/v1/events' \
  -H 'Authorization: Bearer tpk_test_4f2a9c8e1b6d0a35' \
  -H 'Accept: application/json'

Node

import { Tupay } from 'tupay'

const tupay = new Tupay(process.env.TUPAY_SECRET_KEY!)

const resultat = await tupay.events.list()

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/events';

$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

Collection

- dataliste· de objetfacultatif
  - idchaînefacultatif
    exemple evt_9f8c1a2b3d4e5f60
  - objectchaînefacultatif
    valeurs : event
  - createdentierfacultatif
    exemple 1767225600
    Secondes Unix. Même instant que createdAt.
  - typechaînefacultatif
    exemple payment.succeeded
  - createdAtchaînefacultatif
    format date-time
    Doublon de created. Lisez created.
  - livemodebooléenfacultatif
  - dataobjetfacultatif
    - objectobjetfacultatif
      Forme identique dans les réponses REST et dans data.object des webhooks : un seul modèle à écrire côté intégrateur.
      - idchaînefacultatif
        format uuid
      - objectchaînefacultatif
        toujours transaction
      - createdentierfacultatif
        Secondes Unix. Même instant que createdAt.
      - amountXpfentierfacultatif
      - amountEurCentsentierfacultatif
        Centimes EUR, pour réconciliation avec le prestataire bancaire.
      - currencychaînefacultatif
        toujours XPF
      - statuschaînefacultatif
        valeurs : pending, processing, succeeded, failed, refunded
      - paymentIntentIdchaînefacultatif
      - customerIdchaîne ou `null`facultatif
        format uuid
        Client rattaché, null pour un encaissement de passage. Développable : expand[]=customer.
      - paymentMethodIdchaîne ou `null`facultatif
        format uuid
        Carte enregistrée débitée, null si le porteur a saisi la sienne. Développable : expand[]=payment_method.
      - offSessionbooléenfacultatif
        Le porteur n'était pas devant son écran.
      - failureCodechaîne ou `null`facultatif
        valeurs : card_declined, expired_card, incorrect_cvc, insufficient_funds, processing_error, authentication_required, null
        Sur un échec : la raison, en code machine stable. authentication_required n'est pas un refus.
      - failureMessagechaîne ou `null`facultatif
        La même raison, en français, montrable au marchand.
      - paymentLinkIdchaîne ou `null`facultatif
        format uuid
      - 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
      - refundedAmountXpfentierfacultatif
        Cumul remboursé. C'est ce champ qui fait foi, pas status : un remboursement partiel laisse status à succeeded.
      - refundedAtchaîne ou `null`facultatif
        format date-time
      - createdAtchaînefacultatif
        format date-time
        Doublon de created. Lisez created.
      - updatedAtchaînefacultatif
        format date-time
- has_morebooléenfacultatif
  Vrai s'il reste au moins un élément dans le sens du parcours en cours. Calculé sans COUNT(*).
- hasMorebooléenfacultatif
  Déprécié, doublon de has_more et de même valeur. Servi au minimum douze mois, puis retiré par une version datée. Lisez has_more.

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