### Získanie nastavení pre prehliadač [#get-the-browser-settings]
Načítajte nastavenia pre prehliadač raz na serveri a pridajte ich do konfigurácie svojho frontendu.
HTTP (fetch)
Node.js SDK
cURL
Túto pomocnú funkciu majte na serveri. Kontroluje chyby HTTP, na požiadanie považuje chýbajúcu platbu objednávky za `null`
a požiadavky automaticky neopakuje.
```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 };
```
API vracia `publishableKey` a `environment`. Hodnotu `apiOrigin` nastavte podľa URL API, ktoré ste volali; nie je to pole
odpovede s konfiguráciou.
```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'
```
Spustite tento príkaz na svojom serveri alebo v dôveryhodnom termináli. V režime platformy pridajte
`--header "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"` ku každému príkazu cURL v tomto sprievodcovi.
```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"
```
Ako konfiguráciu pre prehliadač použite vrátený `publishableKey` a origin vašej `TAPAYA_CHECKOUT_API_URL`.
Obe hodnoty môžete bezpečne vložiť do stránky. Publishable key má predponu `pk_test_` pri testovacích kľúčoch brány a `pk_live_`
pri ostrých kľúčoch brány. Loaderu vždy odovzdávajte `apiOrigin` vrátený vaším serverom, aby prehliadač aj server
zostali v tom istom prostredí.
### Pridanie polí pre kartu [#add-the-card-fields]
Pridajte kontajner do svojho existujúceho formulára pokladne:
```html title="checkout.html"
```
Načítajte Tapaya a pripojte polia. `prepare` je endpoint, ktorý pridáte v ďalšom kroku.
```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')
```
Po pripojení polia zavolajú `prepare`, aby nadviazali na existujúcu platbu objednávky. Opätovné načítanie stránky počas platby
nikdy nevedie k ďalšiemu zaťaženiu karty: stránka namiesto toho zobrazí aktuálny stav platby.
### Vrátenie platby objednávky [#return-the-orders-payment]
Pripojte tento handler k `POST /api/payments`. `getCheckoutOrder()` je funkcia vašej vlastnej aplikácie: autentifikuje
zákazníka, skontroluje jeho prístup k objednávke a vráti jej uložené `id`, `amount`, `currency` a `status`. Na túto routu
uplatnite svoju obvyklú ochranu proti CSRF.
HTTP (fetch)
Node.js SDK
cURL
Skôr ako vytvoríte pokus, načítajte existujúcu platbu. Nevyriešenú platbu použite znova a ďalší pokus vytvorte
iba po zamietnutí alebo zrušení s `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' } },
);
}
```
Používajte kód meny veľkými písmenami a uložené ID objednávky s dĺžkou najviac 200 znakov. Po začatí platby
údaje objednávky nemeňte. Pri vypršaní časového limitu znova načítajte platbu objednávky a až potom rozhodnite, či je potrebný nový pokus.
Nikdy negenerujte nový kľúč len preto, že sa stratila odpoveď.
```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()` vracia platbu objednávky. Vytvorí prvý pokus, nevyriešený pokus vráti bez zmeny a po zamietnutí
vytvorí ďalší pokus. Idempotency keys si odvodzuje sám, takže jeho volanie pri každom načítaní stránky a
odoslaní nikdy nevedie k druhému zaťaženiu karty. Keď sa platba začne, zafixujte celkovú sumu: `prepare()` vyhodí
`TapayaOrderMismatchError`, ak suma alebo mena objednávky už nezodpovedajú jej platbe.
Najprv vyhľadajte platbu objednávky. Tieto príklady používajú objednávku na 121,00 EUR uloženú na vašom serveri. `404` znamená,
že sa nenašla žiadna platba; iné zlyhania HTTP neoprávňujú na vytvorenie ďalšieho pokusu.
```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"
```
Ak žiadna platba neexistuje a objednávka môže platbu stále prijať, vytvorte prvý pokus:
```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"}'
```
Existujúcu nevyriešenú platbu použite znova. Po `declined` alebo `cancelled` vytvorte ďalší pokus iba vtedy, keď je
`retryAllowed` rovné `true`. Pre tento pokus zopakujte POST s rovnakými údajmi objednávky a kľúčom
`order-1001:after:`, kde zástupný text nahradíte vráteným `id`. Tento kľúč používajte aj pri
opakovaní požiadavky. Po vypršaní časového limitu objednávku znova vyhľadajte; nepredpokladajte, že POST zlyhal.
cURL ukazuje volania API. Handler `POST /api/payments` vašej aplikácie, chránený autentifikáciou, musí poliam pre kartu vracať
`{ clientSecret, status }`. Stav z API preveďte podľa tabuľky nižšie a pošlite
`clientSecret: null`, keď vaša objednávka už platbu neprijíma. Tieto odpovede nikdy nevkladajte do zdieľaných logov terminálu.
REST API vracia stavy platby. Node SDK ich prevádza na `status`, ktorý polia pre kartu očakávajú; integrácie cez fetch a cURL
používajú rovnaký prevod vo svojom vlastnom endpointe prepare:
| `status` v API | `status` endpointu prepare |
| ----------------------------------------------------------------------------------------- | -------------------------- |
| `successful` | `completed` |
| `declined` alebo `cancelled` s `retryAllowed: false` | `ended` |
| `ready`, `pending`, `action_required` alebo zamietnutie či zrušenie, ktoré možno opakovať | `open` |
* **Sumu berte z uloženej objednávky,** v celých najmenších jednotkách meny, nikdy z prehliadača. Keď sa platba začne, zafixujte
celkovú sumu.
* **Odpovedajte aj pri dokončených objednávkach.** Objednávka, ktorá je už zaplatená alebo ktorú dokončila vaša plánovaná úloha, stále vracia
`status` svojej platby, takže opätovné načítanie zobrazí výsledok namiesto chyby. Nikdy nedostane client secret,
takže zákazník nemôže zaplatiť objednávku, za ktorú už platbu neprijímate.
* **Jedna úspešná platba na objednávku.** Každé zamietnutie nastaví `retryAllowed`, takže zákazník môže skúsiť inú kartu pre
tú istú objednávku. Limit je zdieľaný s [hostovaným Checkoutom](/online/integration/api_integration#one-payment-per-order).
* **Chráňte client secret.** Posielajte ho iba zákazníkovi, ktorý je oprávnený túto objednávku zaplatiť, a nikdy ho nelogujte.
* **Počítajte s holou požiadavkou POST.** Polia pre kartu posielajú POST na `prepare` na vašom vlastnom origine s cookies a bez tela. Odmietajú
presmerovania a nikdy požiadavku automaticky neopakujú. Pre vlastné hlavičky, CSRF tokeny alebo telo požiadavky odovzdajte namiesto URL
funkciu, ktorá vracia rovnaký JSON: `prepare: async () => (await fetch(…)).json()`.
### Odoslanie z vášho handlera [#submit-from-your-handler]
Pridajte toto do toho istého skriptu. Váš handler zvaliduje formulár a zavolá `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()` zavolá pre platbu `prepare`, potom zvaliduje kartu, vykoná 3-D Secure a potvrdí platbu
v Tapaya.
### Zobrazenie výsledku [#show-the-outcome]
`onChange` dostane `snapshot` platby pri každej jeho zmene, vrátane načítania stránky s platbou, ktorá
je už dokončená. Riaďte sa hodnotou `snapshot.outcome`:
| `outcome` | Čo zobraziť |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Tlačidlo Pay, aktívne, kým je `canSubmit` true. Po zamietnutí zostáva `open` a ďalšie `submit()` dostane nový pokus. |
| `pending` | Indikátor priebehu. Výsledok zatiaľ nie je známy, takže nemožno nič zaplatiť znova. SDK kontroluje stav automaticky, kým je stránka viditeľná. |
| `completed` | Vašu potvrdzovaciu stránku. Tam váš server objednávku overí. |
| `ended` | Novú pokladňu. Pre túto objednávku už nie je možný žiadny ďalší pokus. |
Keď sa zobrazenie vašej pokladne odpája (unmount), zavolajte `payment.destroy()`. V Reacte použite `usePayment()` z
`@tapayadot/checkout/react`. Prijíma rovnaké možnosti a navyše `publishableKey` a `apiOrigin` a vracia
`fieldRef` pre kontajner, aktuálny `snapshot` a `submit()`.
### Overenie pred vybavením [#verify-before-fulfilling]
Výsledok v prehliadači slúži iba na zobrazenie. Na potvrdzovacej stránke načítajte platbu objednávky na svojom serveri a objednávku vybavte
iba vtedy, keď je platba dokončená:
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()` nikdy nevytvára platbu a pred prvým pokusom vracia `null`. Vyhodí
`TapayaOrderMismatchError`, keď sa suma alebo mena líšia od vašej objednávky.
Aktuálnu platbu objednávky načítajte potom, ako prehliadač skončí, alebo keď kontrolujete neistý výsledok:
```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"
```
Pred vybavením ukážkovej objednávky overte `merchantOrderId: "order-1001"`, `amount: 12100`, `currency: "EUR"`
a `status: "successful"`. Vrátené `id` platby uložte k svojej objednávke. Samotná odpoveď HTTP 200 platbu nedokazuje.
Zabezpečte, aby `markOrderPaid()` zaznamenala platbu iba raz, aj keď sa volá opakovane, a vybavenie spúšťajte z tohto
uloženého stavu.
Zákazník môže zatvoriť kartu prehliadača skôr, ako sa otvorí potvrdzovacia stránka. Spustite plánovanú úlohu, ktorá pre nezaplatené objednávky volá `verify()` alebo
číta `GET /merchant/payments?merchantOrderId=...`, s rovnakými kontrolami. Zamietnuté a
zrušené pokusy umožňujú nový pokus, takže nezaplatená objednávka zostáva `open`: uvoľnite ju podľa vlastného harmonogramu, a
to iba vtedy, keď jej `paymentStatus` nie je `pending`. Neúspešná požiadavka alebo vypršanie časového limitu nie je zamietnutie, preto objednávku nechajte
rezervovanú, kým platba nemá známy výsledok.