### Effectuez l’onboarding de votre commerçant [#onboard-your-merchant] Effectuez l’[onboarding du commerçant](/merchants/onboarding) avec la fonctionnalité de paiements en ligne, ou avec les paiements en ligne et en magasin. Un commerçant qui utilise uniquement le Checkout n’a pas besoin de terminal. Indiquez le site web de la boutique et les informations sur l’activité en ligne, puis attendez l’approbation du processeur. La seule création d’une fiche commerçant ou d’une clé API n’active pas les paiements. Ouvrez **Checkout** dans la [Tapaya Platform](https://platform.tapaya.com/checkout-settings). Les commerçants qui demandent les paiements en ligne y apparaissent automatiquement, y compris ceux en attente d’approbation. Poursuivez lorsque le commerçant est **Ready**. Ouvrez les **Settings** du commerçant. Sous **Merchant API key redirects**, ajoutez votre boutique à **Allowed websites** et définissez les URL de succès et d’annulation par défaut. Une plateforme qui utilise la Secret key de l’organisation les définit plutôt sous **Organization defaults**. Les exemples utilisent `https://shop.example`. Consultez les [paramètres du Checkout](/online/integration/checkout_settings) pour les portefeuilles et l’image de marque. ### Stockez votre clé sur le serveur [#store-your-key-on-the-server] Dans les **Settings** du commerçant, sélectionnez **Create merchant key** et copiez la clé `tapaya_test_…`. Elle ne s’affiche qu’une seule fois. Conservez-la uniquement dans la configuration côté serveur. Elle n’a jamais sa place dans le code du navigateur ni dans le gestionnaire de versions. ```bash title=".env" TAPAYA_ENVIRONMENT=sandbox TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com TAPAYA_SECRET_KEY=tapaya_test_... ``` Le SDK lit automatiquement `TAPAYA_SECRET_KEY` et `TAPAYA_ENVIRONMENT`. Les exemples HTTP ci-dessous utilisent `TAPAYA_CHECKOUT_API_URL`. Chargez les variables dans le processus de votre serveur ; le SDK ne charge pas les fichiers `.env`. Envoyez la clé sous la forme `Authorization: Bearer `. Une clé de commerçant sélectionne son commerçant, aucun autre en-tête n’est donc nécessaire. Une plateforme qui sert de nombreux commerçants utilise plutôt la Secret key de l’organisation et envoie `X-Tapaya-Merchant-Token` dans chaque requête. Voir [Authentification du Checkout](/online/integration/api_integration#authentication). ### Créez une session Checkout [#create-a-checkout-session] Lorsque le client clique sur **Checkout** dans votre boutique, calculez le total final sur votre serveur, enregistrez la commande avec une clé de tentative unique et créez une session. `merchantOrderId` est obligatoire, et une commande ne peut être payée qu’une seule fois. Les montants sont exprimés en unités mineures : `12100` correspond donc à 121,00 EUR. Pour Node.js 22.13.0 ou version ultérieure, installez le SDK ESM avant d’utiliser l’exemple **Node.js SDK** : npm pnpm Bun ```sh npm install @tapayadot/checkout ``` ```sh pnpm add @tapayadot/checkout ``` ```sh bun add @tapayadot/checkout ``` HTTP (fetch) Node.js SDK cURL ```js title="server/checkout.js" const response = await fetch( new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL), { method: 'POST', headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`, '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', }), }, ); if (!response.ok) throw new Error(`Checkout failed (${response.status})`); const session = await response.json(); ``` ```ts title="server/checkout.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); 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 }, ); ``` ```bash title="Terminal" curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \ --header "Authorization: Bearer $TAPAYA_SECRET_KEY" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: order-1001-checkout-1' \ --data '{ "merchantOrderId": "order-1001", "amount": 12100, "currency": "EUR", "successUrl": "https://shop.example/checkout/return", "cancelUrl": "https://shop.example/checkout/cancel" }' ``` Si la requête expire, relancez-la avec la **même** clé et le même corps. L’API rejoue la session d’origine au lieu d’en créer une deuxième. ### Redirigez le client [#redirect-the-customer] Enregistrez `session.id` avec votre commande, puis envoyez le navigateur vers `session.url` avec HTTP 303. Utilisez l’URL exactement telle qu’elle est renvoyée. ```ts // First persist session.id as the order's checkoutSessionId. return Response.redirect(session.url, 303); ``` Tapaya affiche le récapitulatif de la commande et le formulaire de paiement sécurisé, et gère la tokenisation, 3-D Secure et le débit. Après un refus, le client peut essayer une autre carte sur la même page. Les sessions acceptent de nouveaux paiements pendant 30 minutes. ### Vérifiez le paiement sur votre serveur [#verify-the-payment-on-your-server] Lorsque le client arrive sur votre URL de succès ou d’annulation, récupérez la session avec votre Secret key et comparez-la avec la commande enregistrée. Une redirection seule ne prouve jamais le paiement. HTTP (fetch) Node.js SDK ```js title="server/return.js" const response = await fetch( new URL( `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`, process.env.TAPAYA_CHECKOUT_API_URL, ), { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } }, ); if (!response.ok) throw new Error(`Status check failed (${response.status})`); const current = await response.json(); ``` ```ts title="server/return.ts" import { Tapaya } from '@tapayadot/checkout'; const tapaya = new Tapaya(); const current = await tapaya.checkout.sessions.get(order.checkoutSessionId); ``` Quelle que soit l’intégration, comparez le résultat avec la commande enregistrée avant de la traiter : ```ts const matches = current.id === order.checkoutSessionId && current.merchantOrderId === order.id && current.amount === order.totalInMinorUnits && current.currency === order.currency; if (matches && current.paymentStatus === 'successful') { await fulfillOnce(order); // idempotent, safe on repeated visits } ``` Si le statut est toujours `unpaid` ou si la récupération échoue, conservez l’ID de session et vérifiez à nouveau. Il n’existe pas encore de webhooks : exécutez donc une tâche de rapprochement pour les clients qui ferment l’onglet avant de revenir.