Démarrage rapide

Effectuez l’onboarding de votre commerçant

Effectuez l’onboarding du commerçant 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. 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 pour les portefeuilles et l’image de marque.

Stockez votre clé sur le serveur

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.

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

Créez une session Checkout

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 install @tapayadot/checkout

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();

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

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.

// 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

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.

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();

Quelle que soit l’intégration, comparez le résultat avec la commande enregistrée avant de la traiter :

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.