### Získání nastavení pro prohlížeč [#get-the-browser-settings]
Načtěte nastavení pro prohlížeč jednou na serveru a přidejte je do konfigurace svého frontendu.
HTTP (fetch)
Node.js SDK
cURL
Tuto pomocnou funkci mějte na serveru. Kontroluje chyby HTTP, na požádání považuje chybějící platbu objednávky za `null`
a požadavky 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 vrací `publishableKey` a `environment`. Hodnotu `apiOrigin` nastavte podle URL API, které jste volali; není to pole
odpovědi s konfigurací.
```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'
```
Spusťte tento příkaz na svém serveru nebo v důvěryhodném terminálu. V režimu platformy přidejte
`--header "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"` ke každému příkazu cURL v tomto průvodci.
```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"
```
Jako konfiguraci pro prohlížeč použijte vrácený `publishableKey` a origin vaší `TAPAYA_CHECKOUT_API_URL`.
Obě hodnoty můžete bezpečně vložit do stránky. Publishable key má předponu `pk_test_`, pokud používáte testovací klíče brány, a `pk_live_`
u ostrých klíčů brány. Loaderu vždy předávejte `apiOrigin` vrácený vaším serverem, aby prohlížeč i server
zůstaly ve stejném prostředí.
### Přidání polí pro kartu [#add-the-card-fields]
Přidejte kontejner do svého stávajícího formuláře pokladny:
```html title="checkout.html"
```
Načtěte Tapaya a připojte pole. `prepare` je endpoint, který přidáte v dalším 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 připojení pole zavolají `prepare`, aby navázala na existující platbu objednávky. Opětovné načtení stránky během platby
nikdy nevede k další platbě: stránka místo toho zobrazí aktuální stav platby.
### Vrácení platby objednávky [#return-the-orders-payment]
Připojte tento handler k `POST /api/payments`. `getCheckoutOrder()` je funkce vaší vlastní aplikace: autentizuje
zákazníka, zkontroluje jeho přístup k objednávce a vrátí její uložené `id`, `amount`, `currency` a `status`. Na tuto routu
uplatněte svou obvyklou ochranu proti CSRF.
HTTP (fetch)
Node.js SDK
cURL
Než vytvoříte pokus, načtěte existující platbu. Nevyřešenou platbu použijte znovu a další pokus vytvořte
pouze po zamítnutí nebo 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žívejte kód měny velkými písmeny a uložené ID objednávky o délce nejvýše 200 znaků. Po zahájení platby
údaje objednávky neměňte. Při vypršení časového limitu znovu načtěte platbu objednávky a teprve pak rozhodněte, zda je potřeba nový pokus.
Nikdy negenerujte nový klíč jen proto, že se ztratila odpověď.
```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()` vrací platbu objednávky. Vytvoří první pokus, nevyřešený pokus vrátí beze změny a po zamítnutí
vytvoří další pokus. Klíče idempotence si odvozuje sám, takže jeho volání při každém načtení stránky a
odeslání nikdy nevytvoří druhou platbu. Jakmile platba začne, zafixujte celkovou částku: `prepare()` vyhodí
`TapayaOrderMismatchError`, pokud částka nebo měna objednávky už neodpovídají její platbě.
Nejprve vyhledejte platbu objednávky. Tyto příklady používají objednávku na 121,00 EUR uloženou na vašem serveru. `404` znamená,
že žádná platba nebyla nalezena; jiná selhání HTTP neopravňují k vytvoření dalšího 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"
```
Pokud žádná platba neexistuje a objednávka může platbu stále přijmout, vytvořte první 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ící nevyřešenou platbu použijte znovu. Po `declined` nebo `cancelled` vytvořte další pokus pouze tehdy, když je
`retryAllowed` rovno `true`. Pro tento pokus zopakujte POST se stejnými údaji objednávky a klíčem
`order-1001:after:`, kde zástupný text nahradíte vráceným `id`. Tento klíč používejte i pro
opakované pokusy o požadavek. Po vypršení časového limitu objednávku znovu vyhledejte; nepředpokládejte, že POST selhal.
cURL ukazuje volání API. Autentizovaný handler `POST /api/payments` vaší aplikace musí polím pro kartu vracet
`{ clientSecret, status }`. Stav z API převeďte podle tabulky níže a pošlete
`clientSecret: null`, když vaše objednávka už platbu nepřijímá. Tyto odpovědi nikdy nevkládejte do sdílených logů terminálu.
REST API vrací stavy platby. Node SDK je převádí na `status`, který pole pro kartu očekávají; integrace přes fetch a cURL
používají stejný převod ve svém vlastním endpointu prepare:
| `status` v API | `status` endpointu prepare |
| ----------------------------------------------------------------------------------- | -------------------------- |
| `successful` | `completed` |
| `declined` nebo `cancelled` s `retryAllowed: false` | `ended` |
| `ready`, `pending`, `action_required` nebo zamítnutí či zrušení, které lze opakovat | `open` |
* **Částku berte z uložené objednávky,** v celých nejmenších jednotkách měny, nikdy z prohlížeče. Jakmile platba začne, zafixujte
celkovou částku.
* **Odpovídejte i u dokončených objednávek.** Objednávka, která je už zaplacená nebo kterou dokončila vaše plánovaná úloha, stále vrací
`status` své platby, takže opětovné načtení zobrazí výsledek místo chyby. Nikdy nedostane client secret,
takže zákazník nemůže zaplatit objednávku, za kterou už platbu nepřijímáte.
* **Jedna úspěšná platba na objednávku.** Každé zamítnutí nastaví `retryAllowed`, takže zákazník může zkusit jinou kartu pro
stejnou objednávku. Limit je sdílený s [Hosted Checkout](/online/integration/api_integration#one-payment-per-order).
* **Chraňte client secret.** Posílejte ho pouze zákazníkovi, který je oprávněn tuto objednávku zaplatit, a nikdy ho nelogujte.
* **Počítejte s prostým požadavkem POST.** Pole pro kartu posílají POST na `prepare` na vašem vlastním originu s cookies a bez těla. Odmítají
přesměrování a nikdy požadavek automaticky neopakují. Pro vlastní hlavičky, CSRF tokeny nebo tělo požadavku předejte místo URL
funkci, která vrací stejný JSON: `prepare: async () => (await fetch(…)).json()`.
### Odeslání z vašeho handleru [#submit-from-your-handler]
Přidejte toto do stejného skriptu. Váš handler zvaliduje formulář 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á pro platbu `prepare`, potom zvaliduje kartu, provede 3-D Secure a potvrdí platbu
u Tapaya.
### Zobrazení výsledku [#show-the-outcome]
`onChange` dostane `snapshot` platby při každé jeho změně, včetně načtení stránky s platbou, která
už je dokončená. Řiďte se hodnotou `snapshot.outcome`:
| `outcome` | Co zobrazit |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Tlačítko Zaplatit, aktivní, dokud je `canSubmit` true. Po zamítnutí zůstává `open` a další `submit()` dostane nový pokus. |
| `pending` | Indikátor průběhu. Výsledek zatím není znám, takže nelze nic zaplatit znovu. SDK kontroluje stav automaticky, dokud je stránka viditelná. |
| `completed` | Vaši potvrzovací stránku. Tam váš server objednávku ověří. |
| `ended` | Novou pokladnu. Pro tuto objednávku už není možný žádný další pokus. |
Když se zobrazení vaší pokladny odpojuje (unmount), zavolejte `payment.destroy()`. V Reactu použijte `usePayment()` z
`@tapayadot/checkout/react`. Přijímá stejné možnosti a navíc `publishableKey` a `apiOrigin` a vrací
`fieldRef` pro kontejner, aktuální `snapshot` a `submit()`.
### Ověření před vyřízením [#verify-before-fulfilling]
Výsledek v prohlížeči slouží jen k zobrazení. Na potvrzovací stránce načtěte platbu objednávky na svém serveru a objednávku vyřiďte
pouze tehdy, když 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áří platbu a před prvním pokusem vrací `null`. Vyhodí
`TapayaOrderMismatchError`, když se částka nebo měna liší od vaší objednávky.
Aktuální platbu objednávky načtěte poté, co prohlížeč skončí, nebo když kontrolujete nejistý výsledek:
```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"
```
Před vyřízením ukázkové objednávky ověřte `merchantOrderId: "order-1001"`, `amount: 12100`, `currency: "EUR"`
a `status: "successful"`. Vrácené `id` platby uložte ke své objednávce. Samotná odpověď HTTP 200 platbu neprokazuje.
Zajistěte, aby `markOrderPaid()` zaznamenala platbu jen jednou, i když je volána opakovaně, a vyřízení spouštějte z tohoto
uloženého stavu.
Zákazník může zavřít kartu prohlížeče dříve, než se otevře potvrzovací stránka. Spusťte plánovanou úlohu, která pro nezaplacené objednávky volá `verify()` nebo
čte `GET /merchant/payments?merchantOrderId=...`, se stejnými kontrolami. Zamítnuté a
zrušené pokusy umožňují nový pokus, takže nezaplacená objednávka zůstává `open`: uvolněte ji podle vlastního harmonogramu, a
to jen tehdy, když její `paymentStatus` není `pending`. Neúspěšný požadavek nebo vypršení časového limitu není zamítnutí, proto objednávku nechte
rezervovanou, dokud platba nemá známý výsledek.