Événements

Rejouer un événement

POSThttps://tupay.apps.lepetittahitien.dev/api/v1/events/{id}/resend

Rejoue un événement vers tous vos endpoints actifs du mode courant.

Le rejeu CRÉE, il ne modifie pas. Une nouvelle livraison est insérée avec un rang supérieur ; l'ancienne reste intacte comme pièce d'audit, et le backoff d'une livraison encore en cours n'est pas perturbé.

L'enveloppe est reconstruite à partir de l'objet stocké et de la version actuelle de l'endpoint. Un endpoint qui aurait changé de version reçoit la forme qu'il attend aujourd'hui, pas celle du jour de l'émission.

⚠️ Votre gestionnaire recevra l'événement une fois de plus avec le même id : dédupliquez dessus.

L'en-tête Idempotency-Key est facultatif ici, et il est HONORÉ : fourni, deux appels ne créent qu'une seule livraison de plus, et le second ne relivre rien. Sans clé, chaque appel crée une livraison supplémentaire, ce qui reste le comportement voulu de cette opération.

Paramètres de chemin

idchaîne· cheminrequis
motif ^evt_exemple evt_9f8c1a2b3d4e5f60
Identifiant d'événement, tel qu'il apparaît dans l'enveloppe reçue.

Paramètres d’en-tête

Idempotency-Keychaîne· en-têtefacultatif
exemple 9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13
Facultative sur cette opération. Fournie, elle garantit qu'un rejeu ne crée pas une seconde ressource : le corps mémorisé est renvoyé tel quel. Absente, chaque appel crée une ressource de plus, comme avant.
Mêmes règles que sur les opérations qui l'exigent : cloisonnement par marchand, refus 409 idempotency_key_reuse sur corps différent, refus 409 idempotency_in_progress pendant l'exécution de la première, et rétention de 24 heures.
Exception, dite franchement : sur POST /api-keys et POST /webhook-endpoints le secret n'est rendu qu'une fois. Il n'est PAS conservé avec le corps mémorisé, sinon il séjournerait 24 heures en base en clair. Un rejeu rend donc la ressource avec son secret à null. La clé garantit qu'une seule ressource existe, pas que le secret soit redonné.

Exemple d'appel

cURL

curl -X POST 'https://tupay.apps.lepetittahitien.dev/api/v1/events/evt_9f8c1a2b3d4e5f60/resend' \
  -H 'Authorization: Bearer tpk_test_4f2a9c8e1b6d0a35' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13'

Node

import { Tupay } from 'tupay'

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

const resultat = await tupay.events.resend('evt_9f8c1a2b3d4e5f60')

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/evt_9f8c1a2b3d4e5f60/resend';

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

$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

Livraisons créées

- dataobjetfacultatif
  - objectchaînefacultatif
    valeurs : event_resend
  - eventIdchaînefacultatif
  - deliveriesentierfacultatif
    Une par endpoint actif.

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

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

Aucun endpoint actif pour ce mode.

Code machine no_endpoint

Rien à rejouer vers personne. Déclarez un endpoint d'abord.

{
  "error": "no_endpoint",
  "type": "conflict",
  "message": "Aucun endpoint actif pour ce mode. Déclarez-en un avant de rejouer.",
  "code": 422
}

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