Tapaya

Embedded Checkout

Add secure card fields and Apple Pay or Google Pay to your own checkout.

Your frontend
Your backend
Tapaya
  1. 1. Your frontend to Your backend: Prepare payment.
  2. 2. Your backend to Tapaya: Create or resume payment.
  3. 3. Tapaya to Your backend: Payment and client secret.
  4. 4. Your backend to Your frontend: Client secret and status.
  5. 5. Your frontend to Tapaya: Confirm card and 3-D Secure.
  6. 6. Tapaya to Your frontend: Payment outcome.
  7. 7. Your backend to Tapaya: Read order's payment.
  8. 8. Tapaya to Your backend: Payment status.
  9. 9. Your backend to Your frontend: Show verified result.

Before you start

Install the SDK

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

npm install @tapayadot/checkout
ImportWhere
@tapayadot/checkoutYour server only. Importing it in a browser build throws, so your API key never reaches a page.
@tapayadot/checkout/clientYour checkout page.
@tapayadot/checkout/reactYour checkout page, if you use React.

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.

Node.js SDKHTTP (fetch) and cURL
KeyTAPAYA_SECRET_KEY, read by new Tapaya()TAPAYA_CHECKOUT_API_KEY
EnvironmentTAPAYA_ENVIRONMENT=sandbox or production. Without it, a tapaya_live_ key selects production and other keys default to sandbox.TAPAYA_CHECKOUT_API_URL: https://api.sandbox.tapaya.com or https://api.tapaya.com
Platform modePass the order's merchantToken to every call, or set it with new Tapaya(key, { merchantToken })Send X-Tapaya-Merchant-Token on every request. The fetch helper reads it from TAPAYA_MERCHANT_TOKEN.

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 from https://js.tapaya.com. 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. Test your integration against the sandbox API while loading the published Tapaya.js script.

Accept a payment

Get the browser settings

Fetch the browser settings once on your server and add them to your frontend configuration.

Keep this helper on your server. It checks HTTP errors, treats a missing order payment as null when requested, and does not retry automatically.

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

The API returns publishableKey and environment. Set apiOrigin from the API URL you called; it is not a field in the configuration response.

Both values are safe to include in your page. Publishable keys use pk_test_ with test gateway keys and pk_live_ with live gateway keys. Always pass the apiOrigin returned by your server to the loader, so the browser and server stay on the same environment.

Add the card fields

Add a container to your existing checkout form:

checkout.html
<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>

Load Tapaya and mount the fields. prepare is the endpoint you add in the next step.

checkout.ts
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')

When the fields mount, they call prepare to resume the order's existing payment. A reload during a payment never charges again: the page shows the payment's current state instead.

Return the order's payment

Connect this handler to POST /api/payments. getCheckoutOrder() is your own application function: authenticate the shopper, check access to their order, and return its stored id, amount, currency, and status. Apply your usual CSRF protection to the route.

Read the existing payment before creating an attempt. Reuse an unresolved payment, and create another attempt only after a decline or cancellation with retryAllowed: true.

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

Use an uppercase currency code and a stored order ID of at most 200 characters. Keep the order details unchanged after payment starts. On a timeout, read the order's payment again before deciding whether it needs a new attempt. Never generate a new key just because a response was lost.

The REST API returns payment states. The Node SDK maps them to the status the card fields expect; fetch and cURL integrations apply the same mapping in their own prepare endpoint:

API statusPrepare endpoint status
successfulcompleted
declined or cancelled, with retryAllowed: falseended
ready, pending, action_required, or a retryable decline or cancellationopen

Submit from your handler

Add this to the same script. Your handler validates your form and calls submit():

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() calls prepare for the payment, then validates the card, runs 3-D Secure, and confirms the payment with Tapaya.

Show the outcome

onChange receives the payment's snapshot whenever it changes, including when the page loads with a payment that has already settled. Follow snapshot.outcome:

outcomeWhat to show
openThe Pay button, enabled while canSubmit is true. A decline stays open, and the next submit() gets a new attempt.
pendingProgress. The result is not known yet, so nothing can be paid again. The SDK checks the status automatically while the page is visible.
completedYour confirmation page. Your server verifies the order there.
endedA new checkout. No further attempt is possible for this order.

Call payment.destroy() when your checkout view unmounts. For React, use usePayment() from @tapayadot/checkout/react. It takes the same options plus publishableKey and apiOrigin, and returns a fieldRef for the container, the current snapshot, and submit().

Verify before fulfilling

The browser result is for display. On your confirmation page, read the order's payment on your server, and fulfill only when it has completed:

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

Make markOrderPaid() record the payment once, even when it is called repeatedly, and trigger fulfillment from that stored state.

Reconcile orders whose shoppers leave

A shopper can close the tab before the confirmation page opens. Run a scheduled job that calls verify() or reads GET /merchant/payments?merchantOrderId=... for unpaid orders, using the same checks. Declined and cancelled attempts allow a new attempt, so an unpaid order stays open: release it on your own schedule, and only while its paymentStatus is not pending. A failed request or timeout is not a decline, so keep the order reserved until the payment has a known outcome.

Fulfill the order

Once your server has verified the payment, ship the goods or grant access. That is the whole flow:

  1. Card fields load in your page
  2. The customer pays without leaving
  3. Your server verifies the payment
  4. You fulfill the order once

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:

checkout-wallets.ts
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.

Customize the fields

Handle errors

Missing something on this page?Request a feature. We attach this page so the team sees the context.