Tapaya
Paiements en ligneGuide d’intégrationHosted Checkout

Hosted Checkout

Créez une session Checkout, redirigez le client et vérifiez le paiement depuis votre serveur.

Envoyez le client vers une page de paiement hébergée par Tapaya pour les cartes, Apple Pay et Google Pay, puis vérifiez le résultat sur votre serveur. Votre page ne manipule jamais les données de carte, et vous n’ajoutez aucun champ de carte à votre boutique.

Your frontend
Your backend
Tapaya
  1. 1. Your backend to Tapaya: Create session.
  2. 2. Tapaya to Your backend: Session ID and URL.
  3. 3. Your backend to Your frontend: Redirect to Checkout.
  4. 4. Your frontend to Tapaya: Open Checkout and pay.
  5. 5. Tapaya to Your frontend: Return to your shop.
  6. 6. Your backend to Tapaya: Retrieve session.
  7. 7. Tapaya to Your backend: Payment status.
  8. 8. Your backend to Your frontend: Show verified result.

Avant de commencer

Choisissez la clé qui correspond à l’entité qui exploite votre backend. Quelle que soit la clé, conservez-la sur votre serveur ; la page Sécurité du Checkout liste les règles côté serveur.

Ensuite, dans Checkout de la Tapaya Platform :

  1. Ajoutez votre commerçant et vérifiez qu’il affiche Ready. Voir Paramètres du Checkout.
  2. Enregistrez votre boutique comme site autorisé, avec des URL de succès et d’annulation par défaut, pour la clé que vous avez choisie. Les exemples utilisent https://shop.example.

Les URL de retour suivent la clé

Les sessions créées avec une clé de commerçant utilisent les URL de retour du commerçant. Les sessions créées avec la Secret key de l’organisation utilisent plutôt les destinations de retour de l’organisation. Les deux ne sont jamais combinées.

Accepter un paiement

Les trois options créent les mêmes sessions Checkout avec les mêmes identifiants. Choisissez-en une ; chaque étape ci-dessous suit votre choix.

Configurez votre serveur

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 :

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

Créez une 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.

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',
	}),
});

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.

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.

OptionNouvelles tentatives automatiques
HTTP (fetch), cURLNon. Répétez la requête vous-même. Voir Idempotence et erreurs.
Node.js SDKJusqu’à 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. 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

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.

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

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.

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';

Traitez la commande une seule fois, et uniquement si elle est payée

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.

Gérer les résultats de paiement

La page Sécurité du Checkout explique ce qu’il faut vérifier et comment relancer une requête au résultat inconnu sans créer de deuxième session.

RésultatCe qu’indique la sessionQue faire
Refuséopen, avec paymentStatus: failedRien. Le client peut essayer une autre carte ou un autre portefeuille sur la même page.
Pas encore connuopen et unpaid pendant que Tapaya confirme le résultatRécupérez à nouveau la session plus tard.
Nouvelle session pour la même commandeLa session impayée précédente indique expiredUtilisez la nouvelle session. Une commande payée, ou dont un paiement est en cours, renvoie HTTP 409. Voir Un paiement par commande.
ExpiréeN’accepte plus de nouveaux paiements 30 minutes après sa créationCréez une nouvelle session si la commande est toujours impayée. Un paiement soumis avant l’expiration aboutit tout de même.

Pas encore de webhooks

Il n’existe pas encore de webhooks pour le Checkout. Exécutez côté serveur une tâche de rapprochement qui récupère les sessions des commandes dont les clients ne reviennent jamais.

Vérifier l’intégration

Il manque quelque chose sur cette page ?Demandez une fonctionnalité. Nous joignons cette page pour que l’équipe ait le contexte.