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.
- 1. Your backend to Tapaya: Create session.
- 2. Tapaya to Your backend: Session ID and URL.
- 3. Your backend to Your frontend: Redirect to Checkout.
- 4. Your frontend to Tapaya: Open Checkout and pay.
- 5. Tapaya to Your frontend: Return to your shop.
- 6. Your backend to Tapaya: Retrieve session.
- 7. Tapaya to Your backend: Payment status.
- 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.
Une seule boutique
Utilisez une clé checkout de commerçant. Elle sélectionne son commerçant, et les exemples de cette page l’utilisent.
Plusieurs commerçants
Utilisez la Secret key de l’organisation et envoyez un jeton de commerçant avec chaque requête.
Ensuite, dans Checkout de la Tapaya Platform :
- Ajoutez votre commerçant et vérifiez qu’il affiche Ready. Voir Paramètres du Checkout.
- 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 :
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.
| Option | Nouvelles tentatives automatiques |
|---|---|
| HTTP (fetch), cURL | Non. Répétez la requête vous-même. Voir Idempotence et erreurs. |
| 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. 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ésultat | Ce qu’indique la session | Que faire |
|---|---|---|
| Refusé | open, avec paymentStatus: failed | Rien. Le client peut essayer une autre carte ou un autre portefeuille sur la même page. |
| Pas encore connu | open et unpaid pendant que Tapaya confirme le résultat | Récupérez à nouveau la session plus tard. |
| Nouvelle session pour la même commande | La session impayée précédente indique expired | Utilisez la nouvelle session. Une commande payée, ou dont un paiement est en cours, renvoie HTTP 409. Voir Un paiement par commande. |
| Expirée | N’accepte plus de nouveaux paiements 30 minutes après sa création | Cré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
Cartes de test
Testez chaque résultat de paiement dans la sandbox.
Liste de contrôle QA
Couvrez les nouvelles tentatives, les paiements interrompus et l’expiration avant de passer en production.
Paramètres du Checkout
Vérifiez l’approbation des commerçants et gérez les destinations de retour, les portefeuilles, l’image de marque et les clés du Checkout dans la Tapaya Platform.
Embedded Checkout
Ajoutez des champs de carte sécurisés ainsi qu’Apple Pay ou Google Pay à votre propre page de paiement.