Embedded Checkout

Put secure card fields inside your own checkout. You own the form and the submit button; Tapaya handles card validation, tokenization, and 3-D Secure. Embedded payments are live for approved merchants, with sandbox available for testing. This guide uses Tapaya.js 0.2.0 and the Node.js SDK 0.3.0.

Before you start

Install the SDK

One package contains the server client, the browser SDK, and the React hook:

npm install @tapayadot/checkout

Configure your server

Embedded payments do not need return URLs. The server examples below come in HTTP (fetch), Node.js SDK, and cURL versions, which all call the same merchant API and leave the browser card fields unchanged.

A merchant checkout key needs nothing else. In platform mode, use the organization Secret key, and have a backend that serves several merchants pick the token from the authenticated order. See Checkout authentication. Client secrets are specific to each payment.

Complete onboarding with online payments and check that the merchant is Ready in Checkout settings.

Allow Tapaya in your CSP

The loader fetches Tapaya.js 0.2.0 from https://js.tapaya.com/checkout/0.2.0/checkout.js; the browser script version is independent of the Node.js SDK version. Add Tapaya's asset origin to your existing Content Security Policy:

script-src https://js.tapaya.com
frame-src https://js.tapaya.com

The browser receives the publishable key and the payment-specific client secret. Your secret merchant API key remains on your server, and card data and payment-provider scripts stay inside Tapaya's frame. For local testing, serve Tapaya.js yourself and pass its origin to the loader, for example loadTapaya(publishableKey, { apiOrigin, origin: 'http://localhost:4191' }).

How it works

1. Your page mounts Tapaya's card fields and points them at an endpoint on your server.
2. When the page loads and when the shopper pays, the card fields call that endpoint. It returns the order's payment as a clientSecret: a one-payment credential the card fields use to confirm the payment directly with Tapaya. Your page code never reads it.
3. Your page follows the payment's outcome. When it completes, your server verifies the payment before you fulfill the order.

Accept a payment

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 };

<form id="checkout">
	<!-- Your other checkout inputs go here. -->
	<div id="card-fields"></div>
	<button type="submit" disabled>Pay</button>
	<p id="message" role="status"></p>
</form>

import { loadTapaya } from '@tapayadot/checkout/client'
import { config } from './config' // { publishableKey, apiOrigin } from your server

const form = document.querySelector<HTMLFormElement>('#checkout')!
const button = form.querySelector<HTMLButtonElement>('button')!
const message = document.querySelector<HTMLElement>('#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')

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' } },
	);
}

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.
	})
})

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);

Add Apple Pay and Google Pay

Wallets appear inside Tapaya's frame next to the card fields. Before they show, check that:

• Wallets are enabled in Checkout settings.
• Apple Pay: the shop has an active shop domain.
• Google Pay in production: a Google Pay merchant ID is configured.
• The shopper's device, browser, and wallet support the method.

Pass wallets with the checkout total in minor units. Tapaya shows the available methods, and unsupported or disabled wallets stay hidden. Use this instead of the card-only createPayment() example:

const payment = tapaya.createPayment({
	prepare: '/api/payments',
	wallets: { amount: order.totalInMinorUnits, currency: order.currency },
	onWalletClick: async () => {
		if (!form.reportValidity()) throw new Error('Complete the checkout details.')
		// Validate the cart and reserve the order on your server.
		const response = await fetch('/api/payments', { method: 'POST' })
		if (!response.ok) throw new Error('Could not prepare the payment.')
		return response.json() // { clientSecret, status }
	},
	onChange: (snapshot) => {
		button.hidden = snapshot.paymentMethod !== 'card'
		button.disabled = !snapshot.canSubmit
		if (snapshot.outcome === 'completed') location.assign('/checkout/confirmation')
	},
})
await payment.mount('#card-fields')

The total displayed in the browser must come from your server, which still calculates and validates the amount when it prepares the payment.

Wallet clicks

The official wallet button opens the native wallet sheet from the shopper's click. onWalletClick validates your checkout and reserves its payment when that button is clicked, never on mount or method selection. Without this callback, wallets use prepare or clientSecret. If you reserve the order only on click, make the mount-time prepare callback resume an existing order without creating one.

Keep your own Pay button visible only when snapshot.paymentMethod is card; wallets use their branded buttons instead of payment.submit(). Wallet outcomes use the same verification and recovery flow as cards. Closing the wallet sheet leaves the checkout available; an uncertain payment stays pending and blocks another charge.

Update the total

Pass wallets: { amount, currency, disabled: true } while required checkout details are incomplete. Update the total or enable the buttons without remounting:

payment.update({ wallets: { amount: 2450, currency: 'EUR', disabled: false } })

Pass wallets: null to hide wallets until the total is ready. Tapaya refuses confirmation if the prepared payment differs from the wallet total. The React usePayment() hook accepts these options and updates the total when wallets changes.

Your own method selector

If your page owns the method selector, pass paymentMethod: 'card', 'apple_pay', or 'google_pay' to render only that method. An unavailable selected wallet shows the walletUnavailable label and reports snapshot.error.code: 'wallet_unavailable' when another payment is safe to start; offer another method in your selector. Lock the selector while snapshot.busy is true or the payment is pending or action_required.

Frames and CSP

The SDK adds allow="payment" to its frame. If your shop is inside another frame, that outer frame must also allow payment. Cross-origin Apple Pay requires Safari 17 or later. Wallet provider scripts stay inside Tapaya's frame, so your page needs no additional provider origins in its CSP.

Handle expired browser access

The client secret expires after 24 hours, and clientSecret is then null. A payment that was never submitted is then cancelled, and the next prepare() starts a new attempt for the same order. A pending payment stays pending in the browser, and the SDK keeps calling your endpoint until your server reports its outcome as status. Server reads still work, so your scheduled job settles it either way.

Diagnose server errors

The Node SDK throws PaymentsApiError for rejected API requests. Inspect its status, code, message, fieldErrors, and requestId on your server. Keep credentials and client secrets out of logs, and show your own shopper-facing text.

Match your branding

The card fields use the merchant's effective checkout color from Checkout settings as their focus accent (colorFocus). Values you pass in appearance.variables override it, and only the variables you set are sent.