### Configurez votre serveur [#set-up-your-server] HTTP (fetch) Node.js SDK cURL Définissez `TAPAYA_CHECKOUT_API_URL` sur `https://api.sandbox.tapaya.com` et stockez votre clé dans `TAPAYA_CHECKOUT_API_KEY`. Appelez l’API avec le `fetch` de votre environnement d’exécution serveur, jamais depuis le navigateur du client. Les exemples lisent ces valeurs via `process.env` ; adaptez cette lecture si votre environnement d’exécution utilise une autre interface pour les secrets. Créez une fonction utilitaire qui vérifie les erreurs HTTP avant de renvoyer le corps de la réponse : ```js title="server/checkout.js" const apiUrl = process.env.TAPAYA_CHECKOUT_API_URL; const apiKey = process.env.TAPAYA_CHECKOUT_API_KEY; async function checkoutRequest(path, options = {}) { const response = await fetch(new URL(path, apiUrl), { ...options, headers: { ...options.headers, Authorization: `Bearer ${apiKey}`, }, redirect: 'error', cache: 'no-store', signal: AbortSignal.timeout(8000), }); if (!response.ok) { throw new Error(`Checkout request failed (${response.status})`); } return response.json(); } ``` Utilisez Node.js 22.13.0 ou version ultérieure, et installez le paquet ESM sur votre serveur : npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` Stockez votre clé dans `TAPAYA_SECRET_KEY` et sélectionnez l’environnement sandbox. Le SDK ne charge pas lui-même les fichiers `.env` : chargez donc ces valeurs dans l’environnement de votre serveur avant de construire le client. ```sh title=".env" TAPAYA_SECRET_KEY=tapaya_test_... TAPAYA_ENVIRONMENT=sandbox ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); // reads TAPAYA_SECRET_KEY ``` Sans `TAPAYA_ENVIRONMENT`, une clé `tapaya_live_` sélectionne la production et les autres clés utilisent la sandbox par défaut. En mode plateforme, transmettez le jeton du commerçant : `new Tapaya(key, { merchantToken })`, ou `merchantToken` à chaque appel. Si votre clé est stockée sous un autre nom, transmettez-la comme premier argument. La [référence du SDK Node.js](/online/integration/node_sdk) couvre les URL d’API personnalisées, les délais d’attente, les nouvelles tentatives et les erreurs. Exécutez ces commandes depuis votre serveur ou un terminal de confiance. Chargez votre clé dans `TAPAYA_CHECKOUT_API_KEY`, tenez-la à l’écart du code du navigateur et du gestionnaire de versions, et faites pointer l’URL de l’API vers la sandbox : ```bash export TAPAYA_CHECKOUT_API_URL='https://api.sandbox.tapaya.com' ``` ### Créez une session [#create-a-session] Calculez le total de la commande sur votre serveur, taxes et livraison comprises. Enregistrez la commande et une `checkoutAttemptKey` unique **avant** d’envoyer la requête, et chargez `order` depuis cet instantané enregistré. `merchantOrderId` est obligatoire. HTTP (fetch) Node.js SDK cURL ```js const session = await checkoutRequest('/merchant/checkout-sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Idempotency-Key': order.checkoutAttemptKey, }, body: JSON.stringify({ merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }), }); ``` ```ts const session = await tapaya.checkout.sessions.create( { merchantOrderId: order.id, amount: order.totalInMinorUnits, currency: order.currency, successUrl: 'https://shop.example/checkout/return', cancelUrl: 'https://shop.example/checkout/cancel', }, { idempotencyKey: order.checkoutAttemptKey }, ); ``` L’exemple débite 121,00 EUR pour `order-1001`, dont 21,00 EUR de TVA et 6,05 EUR de livraison, avec l’idempotency key enregistrée `order-1001-checkout-1`. Remplacez ces valeurs par les informations de votre commande enregistrée. ```bash curl --request POST \ "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "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" }' ``` La réponse contient l’`id` de la session et l’`url` hébergée. Pour les récapitulatifs d’articles, la ventilation des taxes, les informations client et tous les champs de la réponse, voir [Créer une session Checkout](/online/integration/api_integration#create-a-checkout-session). **Si la requête échoue ou expire,** relancez-la avec la même clé et un corps inchangé. Ne générez jamais de nouvelle clé pour un résultat incertain : un corps modifié avec la même clé renvoie HTTP 409. | Option | Nouvelles tentatives automatiques | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP (fetch), cURL | Non. Répétez la requête vous-même. Voir [Idempotence et erreurs](/online/integration/api_integration#idempotency-and-errors). | | Node.js SDK | Jusqu’à deux fois après une erreur de connexion, un dépassement de délai ou une réponse HTTP 429, 502, 503 ou 504, avec la même clé et le même corps. Voir [Idempotence et nouvelles tentatives](/online/integration/node_sdk#idempotency-and-retries). D’un appel distinct à l’autre ou après un redémarrage, transmettez votre clé enregistrée : si vous l’omettez, une nouvelle clé est générée à chaque appel. | ### Redirigez le client [#redirect-the-customer] Enregistrez `session.id` avec votre commande en tant que `checkoutSessionId`, puis envoyez le navigateur vers `session.url` avec HTTP 303\. Utilisez l’URL sans la modifier plutôt que de la construire vous-même. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Si votre framework utilise une autre API de réponse, envoyez HTTP 303 avec `session.url` dans l’en-tête `Location`. Avec cURL, ouvrez l’`url` renvoyée dans votre navigateur pour tester le paiement manuellement. ### Vérifiez le paiement [#verify-the-payment] Dans votre gestionnaire de retour, identifiez la commande à partir du contexte de checkout authentifié de votre application et récupérez sa session enregistrée depuis votre serveur. Faites-le aussi sur l’URL d’annulation : une visite de l’une ou l’autre URL ne prouve rien. HTTP (fetch) Node.js SDK cURL ```js const current = await checkoutRequest( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, ); if ( current.id !== order.checkoutSessionId || current.merchantOrderId !== order.id || current.amount !== order.totalInMinorUnits || current.currency !== order.currency ) { throw new Error('Checkout session does not match the order'); } const paid = current.paymentStatus === 'successful'; ``` ```ts const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); if ( current.id !== order.checkoutSessionId || current.merchantOrderId !== order.id || current.amount !== order.totalInMinorUnits || current.currency !== order.currency ) { throw new Error('Checkout session does not match the order'); } const paid = current.paymentStatus === 'successful'; ``` Chargez l’ID de session enregistré avec votre commande dans `CHECKOUT_SESSION_ID` : ```bash curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/$CHECKOUT_SESSION_ID" \ --fail-with-body --silent --show-error --max-time 8 \ --header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" ``` Pour la commande d’exemple, vérifiez que `id` correspond à l’ID de session enregistré, que `merchantOrderId` vaut `order-1001`, que `amount` vaut `12100`, que `currency` vaut `EUR` et que `paymentStatus` vaut `successful`. Une réponse HTTP 200 seule ne prouve pas le paiement. Enregistrez le paiement et traitez la commande uniquement lorsque la session correspond à votre commande enregistrée et que `paymentStatus` vaut `successful`, et enregistrez-le de manière atomique pour que cela ne se produise qu’une fois. Si la récupération échoue ou si le paiement n’est pas résolu, conservez l’ID de session et vérifiez à nouveau. Voir [Statut du paiement](/online/integration/api_integration#payment-status).