Découvrez Tapaya Checkout

Tapaya Checkout apporte le paiement en ligne à Tapaya. Vos commerçants peuvent accepter les cartes, Apple Pay et Google Pay sur n'importe quel site web, et vous choisissez quelle part du paiement vous gérez vous-même.

• Hosted Checkout. Votre serveur crée une session et redirige le client vers une page de paiement sécurisée hébergée par Tapaya. Presque aucun travail côté front-end n'est nécessaire.
• Embedded Checkout. Des champs de carte sécurisés et des boutons de portefeuille s'intègrent directement dans votre propre page de paiement, à côté de votre propre bouton Payer.

Les deux reposent sur le même modèle côté serveur : créer, rediriger ou intégrer, puis vérifier sur votre serveur avant de traiter la commande. Vous pouvez commencer dès aujourd'hui dans le sandbox sur docs.tapaya.com.

Qu'est-ce que Tapaya Checkout ?

Tapaya Checkout est la partie en ligne de Tapaya. Il encaisse pour vos commerçants les paiements par carte, Apple Pay et Google Pay, via une seule API et un seul SDK Node.js. Le principe est le même que pour les paiements en magasin : vous intégrez une fois, l'expérience du commerçant reste dans votre produit, et Tapaya gère toute la complexité des paiements en arrière-plan.

• Hosted Checkout vous offre une page de paiement prête à l'emploi sur le domaine de Tapaya, sur ordinateur comme sur mobile.
• Embedded Checkout vous offre des champs sécurisés à intégrer dans votre propre page. Les données de carte restent dans le cadre (iframe) de Tapaya et n'atteignent jamais votre page.

Les deux s'appuient sur les mêmes briques : une clé côté serveur, des montants exprimés dans la plus petite unité de la devise (1880 signifie donc 18,80 EUR), des requêtes idempotentes et une vérification côté serveur. Une fois l'une construite, vous connaissez déjà l'essentiel de l'autre.

Hosted ou Embedded : laquelle choisir ?

En cas de doute, commencez par Hosted Checkout. Passer ensuite à Embedded réutilise les mêmes clés, le même modèle de commande et la même logique de vérification.

Hosted Checkout en cinq étapes

1. Créez une session sur votre serveur. Appelez POST /merchant/checkout-sessions avec merchantOrderId, amount (dans la plus petite unité), currency, customer, successUrl et cancelUrl. Envoyez un en-tête Idempotency-Key.
2. Enregistrez l'ID de session sur la commande.
3. Redirigez le navigateur vers session.url avec un HTTP 303. Utilisez l'URL exactement telle qu'elle est renvoyée.
4. Le client paie sur la page hébergée. En cas de refus, il peut réessayer une carte sur la même page. Les sessions acceptent les paiements pendant 30 minutes.
5. Vérifiez sur votre serveur. Lorsque le client revient sur l'une des deux URL de retour, appelez GET /merchant/checkout-sessions/{id}. Vérifiez que l'ID, l'ID de commande, le montant et la devise correspondent à votre commande, et ne traitez la commande que si paymentStatus vaut successful.

Avec le SDK Node.js (npm install @tapayadot/checkout, Node.js 22.13.0 ou plus récent), l'essentiel ressemble à ceci :

import { Tapaya } from '@tapayadot/checkout'

// Reads TAPAYA_SECRET_KEY from the server environment.
const tapaya = new Tapaya()

// 1–3. Create the session and redirect the customer
const session = await tapaya.checkout.sessions.create(params, { idempotencyKey })
return Response.redirect(session.url, 303)

// 5. Later, on the return URL: verify before you fulfil
const current = await tapaya.checkout.sessions.get(sessionId)

L'ensemble des paramètres se trouve dans le type CreateHostedCheckoutSessionParams et dans le guide Hosted Checkout.

Embedded Checkout : des champs sécurisés dans votre propre page

Embedded Checkout répartit le travail entre votre page et un petit endpoint prepare sur votre serveur. Dans le navigateur, vous chargez Tapaya depuis @tapayadot/checkout/client et vous intégrez les champs :

import { loadTapaya } from '@tapayadot/checkout/client'

const tapaya = await loadTapaya(publishableKey, { apiOrigin })
const payment = tapaya.createPayment({
  prepare: '/api/payments', // your server endpoint
  wallets: { amount: 1880, currency: 'EUR' },
  onChange: (snapshot) => { /* enable Pay when snapshot.canSubmit */ },
})
payment.mount('#card-fields')

// In your form handler:
await payment.submit() // validates, runs 3-D Secure, confirms

Sur votre serveur, l'endpoint prepare charge la commande et réutilise un paiement existant s'il y en a un. Sinon, il en crée un avec POST /merchant/payments et une clé d'idempotence. Il renvoie ensuite { clientSecret, status }. Les applications React peuvent utiliser usePayment() depuis @tapayadot/checkout/react.

Quelques points à connaître :

• Ajoutez https://js.tapaya.com à script-src et frame-src dans votre Content Security Policy.
• N'importez @tapayadot/checkout que côté serveur. Le navigateur utilise le point d'entrée /client.
• snapshot.outcome vous indique quoi afficher : open, pending, completed ou ended.
• Les boutons de portefeuille n'apparaissent que là où ils sont pris en charge et activés. Apple Pay nécessite un domaine de boutique actif, et Google Pay en production nécessite un identifiant marchand.

Le parcours complet est décrit dans le guide Embedded Checkout.

Conçu pour des intégrations fiables

Les paiements échouent de façon désordonnée : un délai dépassé, un client qui ferme l'onglet, une relance qui arrive deux fois. Tapaya Checkout est conçu pour que vous puissiez gérer chacun de ces cas.

• Des clés d'idempotence à chaque création. Relancez avec la même clé et le même corps, et vous récupérez la session ou le paiement d'origine. Un corps modifié renvoie un HTTP 409.
• Des relances intégrées dans le SDK Node.js. Par défaut, il relance deux fois en cas d'erreur de connexion, de délai dépassé et de HTTP 429, 502, 503 et 504, avec un délai d'attente aléatoire (jitter).
• Un paiement par commande. Une nouvelle session pour la même commande fait expirer la précédente. Une commande payée, ou avec un paiement en cours, est refusée.
• Webhooks et interrogation. Abonnez-vous aux événements de session et continuez à vérifier les sessions non résolues en solution de repli.
• Vérifier, puis traiter, une seule fois. Une visite sur votre URL de succès ne prouve rien à elle seule. Confirmez toujours le statut sur votre serveur et enregistrez le traitement de la commande de manière atomique.

Avant la mise en production, testez chaque issue avec les cartes de test du sandbox et parcourez la checklist QA.

Développez plus vite avec le serveur MCP de la documentation Tapaya

La documentation de Tapaya dispose de son propre serveur MCP. Vos outils de développement IA peuvent y rechercher dans les guides et consulter les endpoints de l'API pendant que vous codez, sans quitter l'éditeur. Il fonctionne avec Claude Code, Claude Desktop, Cursor, VS Code, Codex et tout autre client MCP. Il est public et ne nécessite aucune clé API.

claude mcp add --transport http tapaya-docs https://docs.tapaya.com/mcp

Il n'appelle jamais l'API Tapaya de production et ne demande jamais de clés. La configuration pour chaque client se trouve dans MCP Setup.

Du sandbox à la production

1. Intégrez le commerçant avec la fonctionnalité de paiement en ligne, et attendez qu'il apparaisse comme Ready dans Checkout sur la Tapaya Platform.
2. Ajoutez votre boutique aux Allowed websites et définissez les URL de succès et d'annulation par défaut.
3. Développez dans le sandbox avec une clé tapaya_test_, conservée uniquement sur votre serveur.
4. Passez en production : une clé de production, TAPAYA_ENVIRONMENT=production et des URL de retour de production.
5. Configurez les portefeuilles pour la production : le domaine de boutique pour Apple Pay et l'identifiant marchand pour Google Pay.

Le guide Quick Start vous mène de zéro à un premier paiement dans le sandbox en quelques appels serveur.

Questions fréquentes

Quels moyens de paiement Tapaya Checkout prend-il en charge ?

Les cartes, Apple Pay et Google Pay, avec Hosted comme avec Embedded Checkout.

Les données de carte transitent-elles par mon serveur ou ma page ?

Non. Avec Hosted Checkout, le client paie sur la page de Tapaya. Avec Embedded Checkout, les champs de carte et 3-D Secure s'exécutent dans le cadre de Tapaya, et les données de carte n'atteignent jamais votre page.

Combien de temps une session Hosted Checkout est-elle valide ?

30 minutes à partir de sa création. Un paiement soumis avant ce délai est tout de même finalisé. Si la commande est toujours impayée ensuite, créez une nouvelle session.

Existe-t-il un SDK ?

Oui, @tapayadot/checkout pour Node.js 22.13.0 ou plus récent. Il couvre Hosted Checkout côté serveur, ainsi que des points d'entrée navigateur et React pour Embedded Checkout. Les autres environnements peuvent appeler directement l'API REST.

Les plateformes peuvent-elles encaisser pour de nombreux commerçants ?

Oui. Utilisez la Secret key de l'organisation et envoyez un jeton de commerçant avec chaque requête.

Pour commencer

Lisez la présentation Online Payments sur docs.tapaya.com, créez une clé de sandbox et effectuez votre premier paiement de test dès aujourd'hui. Des questions sur votre intégration ? Écrivez à developers@tapaya.com.