Intégration API

Votre backend crée une session Checkout pour chaque commande et la récupère pour vérifier le paiement.

Pour Node.js, le SDK @tapayadot/checkout fournit des méthodes typées create() et get() pour ces endpoints. Il lit TAPAYA_SECRET_KEY par défaut. Les exemples HTTP de cette page transmettent explicitement TAPAYA_CHECKOUT_API_KEY.

Authentification

Chaque appel au Checkout se fait de serveur à serveur et envoie une clé comme jeton bearer :

Authorization: Bearer <key>

Choisissez le mode qui correspond à l’entité qui exploite le backend. Quelle que soit la clé, conservez-la sur votre serveur ; voir Sécurité du Checkout.

Mode commerçant

Utilisez ce mode lorsque le backend sert une seule boutique. Créez une clé checkout de commerçant dans les paramètres du Checkout : ouvrez le commerçant et sélectionnez Create merchant key. La clé commence par tapaya_test_ dans la sandbox ou par tapaya_live_ en production et correspond exactement à ce commerçant.

Authorization: Bearer <merchant-checkout-key>

X-Tapaya-Merchant-Token est facultatif dans ce mode. Si vous l’envoyez, il doit désigner le même commerçant.

La plateforme n’affiche la clé qu’une seule fois et n’en stocke que le hash. Pour effectuer une rotation, créez une clé de remplacement avant de révoquer l’ancienne. La révocation d’une clé n’affecte pas les autres clés de commerçant, les clés de l’organisation ni les client secrets déjà émis vers des navigateurs.

Mode plateforme

Utilisez ce mode lorsqu’un même backend agit pour de nombreux commerçants, comme une marketplace ou une plateforme de livraison de repas. Envoyez la Secret key de l’organisation, disponible sur la page API Keys, et le jeton du commerçant dans chaque requête :

Authorization: Bearer <secret-key>
X-Tapaya-Merchant-Token: <merchant-token>

Il n’y a pas de commerçant par défaut. Une requête sans cet en-tête renvoie HTTP 401. Le commerçant doit appartenir à l’organisation de la clé. Copiez les jetons de commerçant depuis le tableau des commerçants dans les paramètres du Checkout. Le jeton identifie le commerçant ; ce n’est pas un secret.

La Secret key de l’organisation est le même identifiant que celui appelé Server Secret Token dans la documentation de la Platform API. Le Checkout exige le préfixe Bearer. Les autres endpoints de la Platform API acceptent le jeton directement. L’onboarding des commerçants et la gestion de l’organisation passent par la Platform API.

Les corps de requête n’acceptent pas de merchantId.

Environnements

Définissez TAPAYA_CHECKOUT_API_URL sur l’origine de l’API de votre environnement. Les paiements hébergés et intégrés sont tous deux disponibles en production. Chaque commerçant doit effectuer l’onboarding, obtenir l’approbation du processeur pour les paiements en ligne et disposer d’une passerelle de paiement configurée. Vérifiez l’état de préparation du commerçant dans les paramètres du Checkout. Utilisez l’URL de session hébergée renvoyée sans la modifier.

Sessions Checkout

curl -X 'POST' "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" \
-H 'Idempotency-Key: order-1001-checkout-1' \
-d '{
        "merchantOrderId": "order-1001",
        "amount": 12100,
        "currency": "EUR",
        "tax": 2100,
        "shipping": 605,
        "taxRate": 21,
        "successUrl": "https://shop.example/checkout/return",
        "cancelUrl": "https://shop.example/checkout/cancel"
    }'

{
    "id": "cs_7Hq2x9LmR4",
    "merchantOrderId": "order-1001",
    "url": "https://checkout.sandbox.tapaya.com/c/cs_7Hq2x9LmR4",
    "status": "open",
    "paymentStatus": "unpaid",
    "amount": 12100,
    "currency": "EUR",
    "tax": 2100,
    "shipping": 605,
    "taxRate": 21,
    "taxBreakdown": [],
    "items": [],
    "expiresAt": "2026-07-15T12:30:00Z",
    "createdAt": "2026-07-15T12:00:00Z"
}

curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/cs_7Hq2x9LmR4" \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"

Responsabilité de la commande et du paiement

Un ID de session Checkout identifie une page Hosted Checkout. Son merchantOrderId le relie à votre commande, tandis que paymentReference identifie la dernière tentative de confirmation. Enregistrez l’ID de session avec la commande afin de pouvoir récupérer le résultat même si le client ferme le navigateur.

La page hébergée utilise des endpoints publics distincts pour charger et confirmer la session. Son ID de session sert d’identifiant d’accès pour ces endpoints. Une intégration commerçant vérifie le paiement via l’endpoint commerçant authentifié.

Un paiement par commande

Le Hosted Checkout et l’Embedded Checkout partagent un même moteur de paiement. Un commerçant peut avoir au plus un paiement réussi par merchantOrderId. Les ID de commande sont propres à chaque commerçant : des commerçants différents, même au sein d’une même organisation, peuvent donc utiliser les mêmes ID.

• La création d’une session pour une commande impayée remplace la session impayée précédente. L’ancienne URL indique expired et ne peut plus accepter de paiement.
• La création d’une session pour une commande déjà payée, ou dont un paiement est en cours, renvoie HTTP 409.
• Après un refus, le client peut essayer une autre carte ou un autre portefeuille dans la même session. Soumettre à nouveau le même jeton de carte ne débite jamais deux fois.
• Tapaya définit la politique 3-D Secure et tente toujours l’authentification.

Idempotence et erreurs

La création exige une Idempotency-Key non vide de 250 caractères au maximum. Pour un même commerçant :

Un refus de carte est un résultat de paiement, et non la preuve qu’une requête HTTP a échoué.