Abonnements

Créer un abonnement

POSThttps://tupay.apps.lepetittahitien.dev/api/v1/subscriptions

Lie un client à un tarif récurrent. La période courante part de maintenant et sa fin est la prochaine échéance, calculée depuis la périodicité du tarif.

Deux refus, et ils sont voulus. Un abonnement qui ne peut pas aboutir n'est pas créé :

| Situation | Réponse | |---|---| | le client n'a aucune carte enregistrée | 409 — il échouerait à la première échéance | | le tarif est ponctuel | 400 — il prélèverait indéfiniment pour un achat unique | | le tarif est désactivé | 409 — les abonnements en cours continuent |

Sans paymentMethod, la carte par défaut du client est retenue. Une carte détachée n'est jamais retenue.

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

Corps de requête application/json · requis

customerchaînerequis
exemple cus_3fa85f64-5717-4562-b3fc-2c963f66afa6
<uuid> ou cus_<uuid>.
pricechaînerequis
exemple price_8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4
<uuid> ou price_<uuid>. Doit être récurrent.
paymentMethodchaînefacultatif
<uuid> ou pm_<uuid>. Absent, la carte par défaut du client est retenue.
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/subscriptions' \
  -H 'Authorization: Bearer tpk_test_4f2a9c8e1b6d0a35' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13' \
  --data '{
  "customer": "cus_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "price": "price_8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4"
}'

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/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TUPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
    'Idempotency-Key': '9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13',
  },
  body: JSON.stringify({
    customer: 'cus_3fa85f64-5717-4562-b3fc-2c963f66afa6',
    price: 'price_8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4',
  }),
})

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

$corps = json_encode([
    'customer' => 'cus_3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'price' => 'price_8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4',
], 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, [
    'Authorization: Bearer tpk_test_4f2a9c8e1b6d0a35',
    '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

Jeton porteur, en-tête Authorization
Authorization: Bearer tpk_live_… ou Authorization: Bearer tpk_test_…

Réponses

201application/json

Abonnement créé

- dataobjetfacultatif
  Un client lié à un tarif récurrent. Le tarif est toujours récurrent — un abonnement sur un tarif ponctuel est refusé, y compris par la base.
  - idchaînefacultatif
    format uuid
  - objectchaînefacultatif
    toujours subscription
  - createdentierfacultatif
    Secondes Unix. Même instant que createdAt.
  - statuschaînefacultatif
    valeurs : active, paused, past_due, canceled
    past_due : le client n'a pas payé et il n'est pas coupé. Nous ne résilions pas à votre place — la décision vous appartient.
  - customerIdchaînefacultatif
    format uuid
    Développable — expand[]=customer.
  - priceIdchaînefacultatif
    format uuid
    Développable — expand[]=price.
  - paymentMethodIdchaînefacultatif
    format uuid
    La carte retenue à la souscription. Non développable : elle porte les quatre derniers chiffres d'une carte, et une liste d'abonnements n'a pas à les faire défiler. Lisez-la par GET /payment-methods/{id}.
  - cancelAtPeriodEndbooléenfacultatif
    Annulation programmée : le service court jusqu'à currentPeriodEnd, puis l'abonnement se ferme.
    Distincte de canceledAt, qui date la cessation effective. Sur un abonnement canceled, ce champ dit comment il s'est terminé : true = comme prévu, false = coupé net.
  - canceledAtentier ou `null`facultatif
    Secondes Unix. null tant que l'abonnement n'a pas cessé.
  - currentPeriodStartentierfacultatif
    Secondes Unix.
  - currentPeriodEndentierfacultatif
    Secondes Unix. Fin de la période courante, donc la prochaine échéance. Il n'y a pas de second champ pour cet instant : deux champs pour une même date finiraient par diverger.
  - 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

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

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

Le client n'a aucun moyen de paiement, ou le tarif est désactivé. La cause est nommée dans le message.

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