### Obtenir les paramètres du navigateur [#get-the-browser-settings]
Récupérez une fois les paramètres du navigateur sur votre serveur et ajoutez-les à la configuration de votre frontend.
HTTP (fetch)
Node.js SDK
cURL
Conservez cette fonction utilitaire sur votre serveur. Elle vérifie les erreurs HTTP, traite un paiement de commande absent comme `null` lorsque c’est demandé,
et ne relance pas automatiquement les requêtes.
```js title="server/tapaya.js"
const apiOrigin = new URL(process.env.TAPAYA_CHECKOUT_API_URL).origin;
const apiKey = process.env.TAPAYA_CHECKOUT_API_KEY;
const merchantToken = process.env.TAPAYA_MERCHANT_TOKEN;
export async function paymentRequest(path, { method = 'GET', body, key, allowMissing = false } = {}) {
const response = await fetch(new URL(path, apiOrigin), {
method,
headers: {
Authorization: `Bearer ${apiKey}`,
...(merchantToken ? { 'X-Tapaya-Merchant-Token': merchantToken } : {}),
...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
...(key ? { 'Idempotency-Key': key } : {}),
},
...(body === undefined ? {} : { body: JSON.stringify(body) }),
redirect: 'error',
cache: 'no-store',
signal: AbortSignal.timeout(35000),
});
if (allowMissing && response.status === 404) return null;
if (!response.ok) throw new Error(`Payment request failed (${response.status})`);
return response.json();
}
const { publishableKey } = await paymentRequest('/merchant/payments/configuration');
export const config = { publishableKey, apiOrigin };
```
L’API renvoie `publishableKey` et `environment`. Définissez `apiOrigin` à partir de l’URL d’API que vous avez appelée ; ce n’est pas un champ
de la réponse de configuration.
```ts title="server/config.ts"
import { Tapaya } from '@tapayadot/checkout'
const tapaya = new Tapaya()
const { publishableKey, apiOrigin } = await tapaya.checkout.configuration()
// Sandbox: publishableKey: 'pk_test_…', apiOrigin: 'https://api.sandbox.tapaya.com'
// Production: publishableKey: 'pk_live_…', apiOrigin: 'https://api.tapaya.com'
```
Exécutez ceci sur votre serveur ou dans un terminal de confiance. En mode plateforme, ajoutez
`--header "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"` à chaque commande cURL de ce guide.
```bash
curl "$TAPAYA_CHECKOUT_API_URL/merchant/payments/configuration" \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY"
```
Utilisez la `publishableKey` renvoyée et l’origine de votre `TAPAYA_CHECKOUT_API_URL` comme configuration du navigateur.
Les deux valeurs peuvent être incluses sans risque dans votre page. Les publishable keys utilisent `pk_test_` avec les clés de passerelle de test et `pk_live_`
avec les clés de passerelle de production. Transmettez toujours au chargeur l’`apiOrigin` renvoyée par votre serveur, afin que le navigateur et le serveur
restent sur le même environnement.
### Ajouter les champs de carte [#add-the-card-fields]
Ajoutez un conteneur à votre formulaire de paiement existant :
```html title="checkout.html"
```
Chargez Tapaya et montez les champs. `prepare` est l’endpoint que vous ajoutez à l’étape suivante.
```ts title="checkout.ts"
import { loadTapaya } from '@tapayadot/checkout/client'
import { config } from './config' // { publishableKey, apiOrigin } from your server
const form = document.querySelector
('#checkout')!
const button = form.querySelector('button')!
const message = document.querySelector('#message')!
const tapaya = await loadTapaya(config.publishableKey, { apiOrigin: config.apiOrigin })
const payment = tapaya.createPayment({
prepare: '/api/payments',
onChange: ({ canSubmit, outcome }) => {
button.disabled = !canSubmit
if (outcome === 'completed') location.assign('/checkout/confirmation')
if (outcome === 'ended') message.textContent = 'This payment cannot be completed. Start a new checkout.'
},
})
await payment.mount('#card-fields')
```
Lorsque les champs sont montés, ils appellent `prepare` pour reprendre le paiement existant de la commande. Un rechargement pendant un paiement ne
débite jamais une seconde fois : la page affiche plutôt l’état actuel du paiement.
### Renvoyer le paiement de la commande [#return-the-orders-payment]
Reliez ce gestionnaire à `POST /api/payments`. `getCheckoutOrder()` est une fonction de votre propre application : authentifiez
le client, vérifiez son accès à sa commande et renvoyez les valeurs enregistrées `id`, `amount`, `currency` et `status`. Appliquez
votre protection CSRF habituelle à la route.
HTTP (fetch)
Node.js SDK
cURL
Lisez le paiement existant avant de créer une tentative. Réutilisez un paiement non résolu, et ne créez une autre tentative
qu’après un refus ou une annulation avec `retryAllowed: true`.
```js title="server/payments.js"
import { paymentRequest } from './tapaya.js';
import { getCheckoutOrder } from './orders.js';
export async function findPayment(order) {
const query = new URLSearchParams({ merchantOrderId: order.id });
const payment = await paymentRequest(`/merchant/payments?${query}`, { allowMissing: true });
if (payment && (payment.merchantOrderId !== order.id ||
payment.amount !== order.amount || payment.currency !== order.currency)) {
throw new Error('Payment does not match the order');
}
return payment;
}
export function browserStatus(payment) {
if (payment.status === 'successful') return 'completed';
if (['declined', 'cancelled'].includes(payment.status) && !payment.retryAllowed) return 'ended';
return 'open';
}
export async function POST(request) {
const order = await getCheckoutOrder(request);
const payable = order.status === 'pending_payment';
let payment = await findPayment(order);
if (payable && (!payment ||
(['declined', 'cancelled'].includes(payment.status) && payment.retryAllowed))) {
// Derive the same key on retries, including after a lost creation response.
let key = `${order.id}:${payment ? `after:${payment.id}` : 'initial'}`;
if (/[^\x21-\x7e]/.test(key)) {
const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key));
key = `prepare:${Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('')}`;
}
payment = await paymentRequest('/merchant/payments', {
method: 'POST', key,
body: { merchantOrderId: order.id, amount: order.amount, currency: order.currency },
});
if (payment.merchantOrderId !== order.id || payment.amount !== order.amount || payment.currency !== order.currency) {
throw new Error('Payment does not match the order');
}
}
if (!payment) return Response.json({ error: 'Order cannot accept payment' }, { status: 409 });
return Response.json(
{ clientSecret: payable ? payment.clientSecret : null, status: browserStatus(payment) },
{ headers: { 'Cache-Control': 'no-store' } },
);
}
```
Utilisez un code de devise en majuscules et un ID de commande enregistré de 200 caractères au maximum. Ne modifiez pas les informations de la commande
une fois le paiement commencé. En cas de dépassement de délai, relisez le paiement de la commande avant de décider s’il faut une nouvelle tentative.
Ne générez jamais de nouvelle clé simplement parce qu’une réponse a été perdue.
```ts title="server/payments.ts"
import { Tapaya } from '@tapayadot/checkout'
import type { PreparedPayment } from '@tapayadot/checkout'
import { getCheckoutOrder } from './orders'
const tapaya = new Tapaya()
export async function POST(request: Request) {
const order = await getCheckoutOrder(request)
const details = { merchantOrderId: order.id, amount: order.amount, currency: order.currency }
// Only an order awaiting payment gets a payable session. Other orders report their payment's outcome.
const payable = order.status === 'pending_payment'
const session = payable
? await tapaya.checkout.sessions.prepare(details)
: await tapaya.checkout.sessions.verify(details)
if (!session) return Response.json({ error: 'Order cannot accept payment' }, { status: 409 })
// The card fields read both values. Your page code never handles them.
return Response.json(
{ clientSecret: payable ? session.clientSecret : null, status: session.status } satisfies PreparedPayment,
{ headers: { 'Cache-Control': 'no-store' } },
)
}
```
`prepare()` renvoie le paiement de la commande. Il crée la première tentative, renvoie sans la modifier une tentative non résolue, et
crée la tentative suivante après un refus. Il dérive lui-même les idempotency keys : l’appeler à chaque chargement de page et à chaque
soumission ne crée donc jamais de second débit. Figez le total dès que le paiement commence : `prepare()` lève
`TapayaOrderMismatchError` si le montant ou la devise de la commande ne correspondent plus à son paiement.
Recherchez d’abord le paiement de la commande. Ces exemples utilisent une commande de 121,00 EUR enregistrée sur votre serveur. Un `404` signifie
qu’aucun paiement n’a été trouvé ; les autres échecs HTTP n’autorisent pas la création d’une autre tentative.
```bash
curl --get "$TAPAYA_CHECKOUT_API_URL/merchant/payments" \
--data-urlencode 'merchantOrderId=order-1001' \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY"
```
S’il n’existe aucun paiement et que la commande peut encore accepter un paiement, créez la première tentative :
```bash
curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/payments" \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-1001:initial' \
--data '{"merchantOrderId":"order-1001","amount":12100,"currency":"EUR"}'
```
Réutilisez un paiement non résolu existant. Après `declined` ou `cancelled`, ne créez une autre tentative que si
`retryAllowed` vaut `true`. Pour cette tentative, répétez le POST avec les mêmes informations de commande et la clé
`order-1001:after:`, en remplaçant l’espace réservé par l’`id` renvoyé. Réutilisez cette clé pour
les nouvelles tentatives. Après un dépassement de délai, recherchez à nouveau la commande ; ne supposez pas que le POST a échoué.
cURL illustre les appels d’API. Le gestionnaire authentifié `POST /api/payments` de votre application doit renvoyer
`{ clientSecret, status }` aux champs de carte. Convertissez le statut de l’API à l’aide du tableau ci-dessous, et envoyez
`clientSecret: null` lorsque votre commande n’accepte plus de paiement. Ne placez jamais ces réponses dans des journaux de terminal partagés.
L’API REST renvoie des états de paiement. Le SDK Node les convertit en `status` attendu par les champs de carte ; les intégrations fetch et cURL
appliquent la même correspondance dans leur propre endpoint prepare :
| `status` de l’API | `status` de l’endpoint prepare |
| ------------------------------------------------------------------------------------------------------ | ------------------------------ |
| `successful` | `completed` |
| `declined` ou `cancelled`, avec `retryAllowed: false` | `ended` |
| `ready`, `pending`, `action_required`, ou un refus ou une annulation permettant une nouvelle tentative | `open` |
* **Prenez le montant dans votre commande enregistrée,** en unités mineures entières, jamais depuis le navigateur. Figez le total dès que
le paiement commence.
* **Répondez aussi pour les commandes finalisées.** Une commande déjà payée, ou que votre tâche planifiée a finalisée, répond toujours
avec le `status` de son paiement, afin qu’un rechargement affiche le résultat au lieu d’une erreur. Elle ne reçoit jamais de client secret,
de sorte que le client ne peut pas payer une commande pour laquelle vous n’acceptez plus de paiement.
* **Un seul paiement réussi par commande.** Chaque refus définit `retryAllowed`, afin que le client puisse essayer une autre carte pour
la même commande. Cette limite est partagée avec le [Hosted Checkout](/online/integration/api_integration#one-payment-per-order).
* **Protégez le client secret.** Envoyez-le uniquement au client autorisé à payer cette commande, et ne le journalisez jamais.
* **Attendez-vous à un POST minimal.** Les champs de carte envoient un POST à `prepare` sur votre propre origine, avec les cookies et sans corps. Ils refusent
les redirections et ne relancent jamais automatiquement la requête. Pour des en-têtes personnalisés, des jetons CSRF ou un corps de requête, transmettez une
fonction qui renvoie le même JSON au lieu de l’URL : `prepare: async () => (await fetch(…)).json()`.
### Soumettre depuis votre gestionnaire [#submit-from-your-handler]
Ajoutez ceci au même script. Votre gestionnaire valide votre formulaire et appelle `submit()` :
```ts title="checkout.ts"
form.addEventListener('submit', async (event) => {
event.preventDefault()
if (!form.reportValidity() || !payment.snapshot.canSubmit) return
await payment.submit().catch(() => {
// The card fields show the reason. The shopper can try again when canSubmit allows it.
})
})
```
`submit()` appelle `prepare` pour le paiement, puis valide la carte, exécute 3-D Secure et confirme le paiement
auprès de Tapaya.
### Afficher le résultat [#show-the-outcome]
`onChange` reçoit le `snapshot` du paiement à chaque changement, y compris lorsque la page se charge avec un paiement
déjà finalisé. Suivez `snapshot.outcome` :
| `outcome` | Ce qu’il faut afficher |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Le bouton de paiement, activé tant que `canSubmit` est vrai. Un refus reste `open`, et le `submit()` suivant obtient une nouvelle tentative. |
| `pending` | Un indicateur de progression. Le résultat n’est pas encore connu, rien ne peut donc être payé à nouveau. Le SDK vérifie automatiquement le statut tant que la page est visible. |
| `completed` | Votre page de confirmation. Votre serveur y vérifie la commande. |
| `ended` | Un nouveau parcours de paiement. Aucune autre tentative n’est possible pour cette commande. |
Appelez `payment.destroy()` lorsque votre vue de paiement est démontée. Pour React, utilisez `usePayment()` de
`@tapayadot/checkout/react`. Il accepte les mêmes options plus `publishableKey` et `apiOrigin`, et renvoie un
`fieldRef` pour le conteneur, le `snapshot` actuel et `submit()`.
### Vérifier avant de traiter la commande [#verify-before-fulfilling]
Le résultat côté navigateur sert à l’affichage. Sur votre page de confirmation, lisez le paiement de la commande sur votre serveur, et ne traitez la commande
que lorsque le paiement est terminé :
HTTP (fetch)
Node.js SDK
cURL
```js title="server/confirmation.js"
import { findPayment } from './payments.js';
const order = await getCheckoutOrder(request);
const payment = await findPayment(order); // Checks order ID, amount, and currency.
if (payment?.status === 'successful') await markOrderPaid(order.id, payment.id);
```
```ts title="server/confirmation.ts"
const order = await getCheckoutOrder(request)
const session = await tapaya.checkout.sessions.verify({
merchantOrderId: order.id,
amount: order.amount,
currency: order.currency,
})
if (session?.status === 'completed') await markOrderPaid(order.id, session.id)
```
`verify()` ne crée jamais de paiement et renvoie `null` avant la première tentative. Il lève
`TapayaOrderMismatchError` lorsque le montant ou la devise diffèrent de votre commande.
Récupérez le paiement actuel de la commande une fois que le navigateur a terminé, ou lorsque vous vérifiez un résultat incertain :
```bash
curl --get "$TAPAYA_CHECKOUT_API_URL/merchant/payments" \
--data-urlencode 'merchantOrderId=order-1001' \
--fail-with-body --silent --show-error --max-time 35 \
--header "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY"
```
Avant de traiter la commande d’exemple, vérifiez `merchantOrderId: "order-1001"`, `amount: 12100`, `currency: "EUR"`
et `status: "successful"`. Enregistrez l’`id` de paiement renvoyé avec votre commande. Une réponse HTTP 200 seule ne prouve pas le paiement.
Faites en sorte que `markOrderPaid()` n’enregistre le paiement qu’une seule fois, même s’il est appelé à plusieurs reprises, et déclenchez le traitement de la commande à partir de cet
état enregistré.
Un client peut fermer l’onglet avant l’ouverture de la page de confirmation. Exécutez une tâche planifiée qui appelle `verify()` ou
lit `GET /merchant/payments?merchantOrderId=...` pour les commandes impayées, avec les mêmes vérifications. Les tentatives refusées et
annulées permettent une nouvelle tentative, de sorte qu’une commande impayée reste `open` : libérez-la selon votre propre calendrier, et
uniquement tant que son `paymentStatus` n’est pas `pending`. Une requête en échec ou un dépassement de délai n’est pas un refus : gardez donc la commande
réservée jusqu’à ce que le paiement ait un résultat connu.