Paiements

Créer un paiement

POSThttps://tupay.apps.lepetittahitien.dev/api/v1/payments/intent

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înefacultatif
format uuid
Facultatif : le marchand est déduit de la clé API. Fourni, il doit correspondre, sinon 403.
paymentLinkIdchaînefacultatif
format uuid
paymentMethodchaînefacultatif
exemple pm_1f9c3d2a-7b4e-4a19-8c05-2d6f8b1e4a73
Carte enregistrée à débiter — <uuid> ou pm_<uuid>. Exige `customer` : sans lui, rien ne permet de vérifier que la carte appartient bien à ce client.
Le débit est tenté dans CE MÊME appel : la réponse porte status: succeeded, ou un 402 si la banque refuse. Un moyen détaché vaut 409.
offSessionbooléenfacultatif
Le porteur n'est pas devant son écran (abonnement, relance). N'a de sens qu'avec paymentMethod.
Hors session, une authentification forte ne peut pas aboutir : la banque rend alors failureCode: authentication_required, et c'est à vous de ramener le porteur devant son écran.
customerchaînefacultatif
exemple cus_8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4
Client à rattacher — <uuid> ou cus_<uuid>. La transaction portera customerId, et expand[]=customer la développera.
Un identifiant inconnu, ou appartenant à un autre marchand, rend 404 avant tout appel au prestataire : aucune intention n'est ouverte chez lui, rien n'est à annuler. Un client supprimé reste acceptable — la suppression ferme la modification de la fiche, pas son usage.
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/payments/intent' \
  -H 'Authorization: Bearer tpk_test_4f2a9c8e1b6d0a35' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 9f8c1a2b-3d4e-4f60-8a71-5b2c9d0e6f13' \
  --data '{
  "amountXpf": 4500,
  "paymentMethod": "pm_1f9c3d2a-7b4e-4a19-8c05-2d6f8b1e4a73",
  "customer": "cus_8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4"
}'

Node

import { Tupay } from 'tupay'

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

const resultat = await tupay.paymentIntents.create({
  amountXpf: 4500,
  paymentMethod: 'pm_1f9c3d2a-7b4e-4a19-8c05-2d6f8b1e4a73',
  customer: 'cus_8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4',
})

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/payments/intent';

$corps = json_encode([
    'amountXpf' => 4500,
    'paymentMethod' => 'pm_1f9c3d2a-7b4e-4a19-8c05-2d6f8b1e4a73',
    'customer' => 'cus_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

Paiement créé

- dataobjetfacultatif
  - objectchaînefacultatif
    toujours payment_intent
  - idchaînefacultatif
    format uuid
    Identifiant Tupay, à conserver : c'est celui que vous retrouverez sur les remboursements, les webhooks et l'export comptable. Tupay n'a pas de ressource « intent » distincte de la transaction, les deux partagent donc cet identifiant.
  - createdentierfacultatif
    Secondes Unix. Même instant que createdAt.
  - livemodebooléenfacultatif
  - clientSecretchaîne ou `null`facultatif
  - statuschaînefacultatif
    valeurs : pending, processing, succeeded, failed, refunded
    pending pour un paiement ordinaire, qui attend le navigateur. succeeded pour un débit sur carte enregistrée, qui aboutit dans cet appel.
  - customerIdchaîne ou `null`facultatif
    format uuid
    Client rattaché, null pour un encaissement de passage.
  - amountXpfentierfacultatif
  - amountEurCentsentierfacultatif
  - 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.
  - intentIdchaînefacultatif
    Identifiant chez le prestataire bancaire. Observable, jamais stable : il ne fait pas partie du contrat. Servi au minimum douze mois, puis retiré par une version datée.
  - transactionIdchaînefacultatif
    format uuid
    Doublon de id et de même valeur. Servi au minimum douze mois, puis retiré par une version datée. Lisez id.

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

402application/json

La banque a refusé le débit. Elle a répondu, et la réponse est non — rien n'est en panne, et retenter à l'identique reproduira le refus.

details.failureCode porte la raison précise, et details.transactionId la transaction, qui EXISTE et porte la même raison : un refus est un résultat, pas une requête perdue.

⚠️ authentication_required n'est pas un refus bancaire : le porteur doit valider une authentification forte. Même statut HTTP, suite différente.

Code machine payment_declined

La banque a dit non. Reprise : demandez un autre moyen de paiement — retenter à l'identique reproduira le refus.

{
  "error": "payment_declined",
  "type": "provider",
  "message": "La banque du porteur a refusé la carte, sans en donner la raison. Invitez-le à en essayer une autre ou à contacter sa banque.",
  "code": 402,
  "failureCode": "card_declined",
  "transactionId": "3c7a1f92-5b4e-4d08-9a61-7e2b0c5d8f34"
}

Code machine payment_declined

Pas un refus. Le porteur est solvable, il lui manque un geste. Reprise : ramenez-le devant son écran pour qu'il valide son authentification forte. Le traiter comme un refus fait abandonner une vente qui allait aboutir.

{
  "error": "payment_declined",
  "type": "provider",
  "message": "La banque exige une authentification forte (3-D Secure) que le porteur n’a pas menée à son terme. Ce n’est PAS un refus : ramenez-le devant son écran pour qu’il la valide.",
  "code": 402,
  "failureCode": "authentication_required",
  "transactionId": "3c7a1f92-5b4e-4d08-9a61-7e2b0c5d8f34"
}

- 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é.
- failureCodechaînefacultatif
  valeurs : card_declined, expired_card, incorrect_cvc, insufficient_funds, processing_error, authentication_required
- transactionIdchaînefacultatif
  format uuid

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

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

502application/json

Le prestataire bancaire a refusé l'opération

Code machine bad_gateway
Refus venu du prestataire, pas de Tupay. Reprise : réessayez.
error valait autrefois le code du prestataire lui-même (card_declined, insufficient_funds…). Il vaut désormais toujours bad_gateway, et le code d'origine part dans providerCode. Ce champ est OBSERVABLE mais pas stable : il ne fait pas partie de notre contrat, ne branchez pas dessus.
```
{
  "error": "bad_gateway",
  "type": "provider",
  "message": "Le prestataire bancaire n’a pas pu traiter la demande. Réessayez dans un instant ; si le refus persiste, le code du prestataire est indiqué dans « providerCode ».",
  "code": 502,
  "providerCode": "card_declined"
}
```
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é.