### Browser-Einstellungen abrufen [#get-the-browser-settings]
Rufen Sie die Browser-Einstellungen einmal auf Ihrem Server ab und fügen Sie sie Ihrer Frontend-Konfiguration hinzu.
HTTP (fetch)
Node.js SDK
cURL
Halten Sie diese Hilfsfunktion auf Ihrem Server. Sie prüft HTTP-Fehler, behandelt auf Wunsch eine fehlende Zahlung der Bestellung als `null`
und wiederholt nicht automatisch.
```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 };
```
Die API gibt `publishableKey` und `environment` zurück. Setzen Sie `apiOrigin` anhand der aufgerufenen API-URL; es ist kein Feld
in der Antwort zur Konfiguration.
```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'
```
Führen Sie dies auf Ihrem Server oder in einem vertrauenswürdigen Terminal aus. Fügen Sie im Plattformmodus
`--header "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"` zu jedem cURL-Befehl in diesem Leitfaden hinzu.
```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"
```
Verwenden Sie den zurückgegebenen `publishableKey` und den Origin Ihrer `TAPAYA_CHECKOUT_API_URL` als Browser-Konfiguration.
Beide Werte können Sie unbedenklich in Ihre Seite aufnehmen. Publishable keys verwenden `pk_test_` mit Test-Gateway-Schlüsseln und `pk_live_`
mit Live-Gateway-Schlüsseln. Übergeben Sie dem Loader immer den von Ihrem Server zurückgegebenen `apiOrigin`, damit Browser und Server
in derselben Umgebung bleiben.
### Kartenfelder hinzufügen [#add-the-card-fields]
Fügen Sie Ihrem bestehenden Checkout-Formular einen Container hinzu:
```html title="checkout.html"
```
Laden Sie Tapaya und binden Sie die Felder ein. `prepare` ist der Endpoint, den Sie im nächsten Schritt hinzufügen.
```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')
```
Beim Einbinden rufen die Felder `prepare` auf, um die bestehende Zahlung der Bestellung fortzusetzen. Ein Neuladen während einer Zahlung führt nie
zu einer erneuten Belastung: Die Seite zeigt stattdessen den aktuellen Zustand der Zahlung.
### Zahlung der Bestellung zurückgeben [#return-the-orders-payment]
Verbinden Sie diesen Handler mit `POST /api/payments`. `getCheckoutOrder()` ist eine Funktion Ihrer eigenen Anwendung: Authentifizieren Sie
den Kunden, prüfen Sie den Zugriff auf seine Bestellung und geben Sie deren gespeicherte Werte `id`, `amount`, `currency` und `status` zurück. Wenden Sie
auf die Route Ihren üblichen CSRF-Schutz an.
HTTP (fetch)
Node.js SDK
cURL
Lesen Sie die bestehende Zahlung, bevor Sie einen Versuch erstellen. Verwenden Sie eine ungeklärte Zahlung erneut und erstellen Sie einen weiteren Versuch
nur nach einer Ablehnung oder einem Abbruch mit `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' } },
);
}
```
Verwenden Sie einen Währungscode in Großbuchstaben und eine gespeicherte Bestell-ID mit höchstens 200 Zeichen. Lassen Sie die Bestelldaten unverändert,
sobald die Zahlung begonnen hat. Lesen Sie bei einem Timeout die Zahlung der Bestellung erneut, bevor Sie entscheiden, ob ein neuer Versuch nötig ist.
Erzeugen Sie niemals einen neuen Schlüssel, nur weil eine Antwort verloren ging.
```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()` gibt die Zahlung der Bestellung zurück. Die Methode erstellt den ersten Versuch, gibt einen ungeklärten Versuch unverändert zurück und
erstellt nach einer Ablehnung den nächsten Versuch. Sie leitet die idempotency keys (Idempotenzschlüssel) selbst ab, sodass ein Aufruf bei jedem Laden der Seite und
jedem Absenden nie eine zweite Belastung erzeugt. Frieren Sie den Gesamtbetrag ein, sobald die Zahlung begonnen hat: `prepare()` wirft
`TapayaOrderMismatchError`, wenn Betrag oder Währung der Bestellung nicht mehr zu ihrer Zahlung passen.
Suchen Sie zuerst die Zahlung der Bestellung. Diese Beispiele verwenden eine auf Ihrem Server gespeicherte Bestellung über 121,00 EUR. Ein `404` bedeutet,
dass keine Zahlung gefunden wurde; andere HTTP-Fehler berechtigen nicht dazu, einen weiteren Versuch zu erstellen.
```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"
```
Wenn keine Zahlung existiert und die Bestellung noch eine Zahlung annehmen kann, erstellen Sie den ersten Versuch:
```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"}'
```
Verwenden Sie eine bestehende ungeklärte Zahlung erneut. Erstellen Sie nach `declined` oder `cancelled` einen weiteren Versuch nur, wenn
`retryAllowed` gleich `true` ist. Wiederholen Sie für diesen Versuch den POST mit denselben Bestelldaten und dem Schlüssel
`order-1001:after:`, wobei Sie den Platzhalter durch die zurückgegebene `id` ersetzen. Verwenden Sie diesen Schlüssel für
Wiederholungen erneut. Suchen Sie nach einem Timeout die Bestellung erneut; gehen Sie nicht davon aus, dass der POST fehlgeschlagen ist.
cURL veranschaulicht die API-Aufrufe. Der authentifizierte Handler `POST /api/payments` Ihrer Anwendung muss
`{ clientSecret, status }` für die Kartenfelder zurückgeben. Bilden Sie den API-Status anhand der Tabelle unten ab und senden Sie
`clientSecret: null`, wenn Ihre Bestellung keine Zahlung mehr annimmt. Legen Sie diese Antworten niemals in gemeinsam genutzten Terminal-Logs ab.
Die REST-API gibt Zahlungsstatus zurück. Das Node SDK bildet sie auf den `status` ab, den die Kartenfelder erwarten; fetch- und
cURL-Integrationen wenden dieselbe Zuordnung in ihrem eigenen prepare-Endpoint an:
| API-`status` | `status` des prepare-Endpoints |
| ------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `successful` | `completed` |
| `declined` oder `cancelled`, mit `retryAllowed: false` | `ended` |
| `ready`, `pending`, `action_required` oder eine wiederholbare Ablehnung bzw. ein wiederholbarer Abbruch | `open` |
* **Übernehmen Sie den Betrag aus Ihrer gespeicherten Bestellung,** als Ganzzahl in der kleinsten Währungseinheit, niemals aus dem Browser. Frieren Sie den Gesamtbetrag ein,
sobald die Zahlung begonnen hat.
* **Antworten Sie auch bei abgeschlossenen Bestellungen.** Eine Bestellung, die bereits bezahlt ist oder die Ihr geplanter Job abgeschlossen hat, antwortet weiterhin
mit dem `status` ihrer Zahlung, sodass ein Neuladen das Ergebnis statt eines Fehlers zeigt. Sie erhält nie ein client secret,
sodass der Kunde keine Bestellung bezahlen kann, für die Sie keine Zahlung mehr annehmen.
* **Eine erfolgreiche Zahlung pro Bestellung.** Jede Ablehnung setzt `retryAllowed`, sodass der Kunde für dieselbe Bestellung eine andere Karte
versuchen kann. Das Limit gilt gemeinsam mit dem [Hosted Checkout](/online/integration/api_integration#one-payment-per-order).
* **Schützen Sie das client secret.** Senden Sie es nur an den Kunden, der berechtigt ist, diese Bestellung zu bezahlen, und protokollieren Sie es nie.
* **Rechnen Sie mit einem einfachen POST.** Die Kartenfelder senden einen POST an `prepare` auf Ihrem eigenen Origin, mit Cookies und ohne Body. Sie lehnen
Weiterleitungen ab und wiederholen die Anfrage nie automatisch. Für eigene Header, CSRF-Tokens oder einen Request-Body übergeben Sie statt der URL eine
Funktion, die dasselbe JSON zurückgibt: `prepare: async () => (await fetch(…)).json()`.
### Aus Ihrem Handler absenden [#submit-from-your-handler]
Fügen Sie dies demselben Skript hinzu. Ihr Handler validiert Ihr Formular und ruft `submit()` auf:
```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()` ruft `prepare` für die Zahlung auf, validiert dann die Karte, führt 3-D Secure aus und bestätigt die Zahlung
bei Tapaya.
### Ergebnis anzeigen [#show-the-outcome]
`onChange` erhält den `snapshot` der Zahlung bei jeder Änderung, auch wenn die Seite mit einer Zahlung lädt, die
bereits abgeschlossen ist. Richten Sie sich nach `snapshot.outcome`:
| `outcome` | Was angezeigt werden soll |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open` | Der Bezahl-Button, aktiviert, solange `canSubmit` true ist. Eine Ablehnung bleibt `open`, und das nächste `submit()` erhält einen neuen Versuch. |
| `pending` | Fortschritt. Das Ergebnis ist noch nicht bekannt, daher kann nichts erneut bezahlt werden. Das SDK prüft den Status automatisch, solange die Seite sichtbar ist. |
| `completed` | Ihre Bestätigungsseite. Dort verifiziert Ihr Server die Bestellung. |
| `ended` | Ein neuer Checkout. Für diese Bestellung ist kein weiterer Versuch möglich. |
Rufen Sie `payment.destroy()` auf, wenn Ihre Checkout-Ansicht ausgehängt wird. Verwenden Sie für React `usePayment()` aus
`@tapayadot/checkout/react`. Der Hook akzeptiert dieselben Optionen plus `publishableKey` und `apiOrigin` und gibt eine
`fieldRef` für den Container, den aktuellen `snapshot` und `submit()` zurück.
### Vor der Abwicklung verifizieren [#verify-before-fulfilling]
Das Ergebnis im Browser dient der Anzeige. Lesen Sie auf Ihrer Bestätigungsseite die Zahlung der Bestellung auf Ihrem Server und wickeln Sie die Bestellung
nur ab, wenn die Zahlung abgeschlossen ist:
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()` erstellt nie eine Zahlung und gibt vor dem ersten Versuch `null` zurück. Die Methode wirft
`TapayaOrderMismatchError`, wenn Betrag oder Währung von Ihrer Bestellung abweichen.
Rufen Sie die aktuelle Zahlung der Bestellung ab, nachdem der Browser fertig ist, oder wenn Sie ein unsicheres Ergebnis prüfen:
```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"
```
Verifizieren Sie vor der Abwicklung der Beispielbestellung `merchantOrderId: "order-1001"`, `amount: 12100`, `currency: "EUR"`
und `status: "successful"`. Speichern Sie die zurückgegebene `id` der Zahlung mit Ihrer Bestellung. HTTP 200 allein beweist keine Zahlung.
Sorgen Sie dafür, dass `markOrderPaid()` die Zahlung genau einmal verbucht, auch bei wiederholten Aufrufen, und lösen Sie die Abwicklung anhand dieses
gespeicherten Zustands aus.
Ein Kunde kann den Tab schließen, bevor sich die Bestätigungsseite öffnet. Betreiben Sie einen geplanten Job, der für unbezahlte Bestellungen `verify()` aufruft oder
`GET /merchant/payments?merchantOrderId=...` liest, mit denselben Prüfungen. Abgelehnte und
abgebrochene Versuche erlauben einen neuen Versuch, daher bleibt eine unbezahlte Bestellung `open`: Geben Sie sie nach Ihrem eigenen Zeitplan frei, und
nur, solange ihr `paymentStatus` nicht `pending` ist. Eine fehlgeschlagene Anfrage oder ein Timeout ist keine Ablehnung, halten Sie die Bestellung daher
reserviert, bis das Ergebnis der Zahlung bekannt ist.