Hosted Checkout

Set up server-side fetch

Use your server runtime's fetch to call the merchant Checkout API. Do not run these requests in the customer's browser.

Set TAPAYA_CHECKOUT_API_URL to https://api.sandbox.tapaya.com and store your key in TAPAYA_CHECKOUT_API_KEY. The examples read these values through process.env; adapt that lookup if your server runtime uses a different secrets interface.

Create a helper that checks HTTP errors before returning the response body:

const apiUrl = process.env.TAPAYA_CHECKOUT_API_URL;
const apiKey = process.env.TAPAYA_CHECKOUT_API_KEY;

async function checkoutRequest(path, options = {}) {
	const response = await fetch(new URL(path, apiUrl), {
		...options,
		headers: {
			...options.headers,
			Authorization: `Bearer ${apiKey}`,
		},
		redirect: 'error',
		cache: 'no-store',
		signal: AbortSignal.timeout(8000),
	});

	if (!response.ok) {
		throw new Error(`Checkout request failed (${response.status})`);
	}

	return response.json();
}

Create a session with fetch

Calculate the order total on your server. Persist the order and a unique checkoutAttemptKey before making the request. merchantOrderId is required. Load order from that stored snapshot, including its ID, currency, and total in minor units.

const session = await checkoutRequest('/merchant/checkout-sessions', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'Idempotency-Key': order.checkoutAttemptKey,
	},
	body: JSON.stringify({
		merchantOrderId: order.id,
		amount: order.totalInMinorUnits,
		currency: order.currency,
		successUrl: 'https://shop.example/checkout/return',
		cancelUrl: 'https://shop.example/checkout/cancel',
	}),
});

Supply the final total, including tax and shipping. For item summaries, tax breakdowns, and customer details, see Create a Checkout Session.

This helper does not retry automatically. If creation times out or its response is lost, retry with the same persisted key and unchanged body. Do not generate a new key for an uncertain result. A changed body with the same key returns HTTP 409. See Idempotency and errors.

Redirect using the HTTP response

Persist session.id with your order before returning a redirect. Use session.url unchanged rather than constructing the Checkout URL.

For a server handler that returns a Web Response, return:

// First persist session.id as the order's checkoutSessionId.
return Response.redirect(session.url, 303);

If your framework uses a different response API, send HTTP 303 with session.url in the Location header.

Verify payment with fetch

In your return handler, resolve the order from your application's authenticated checkout context. Load its stored checkoutSessionId and retrieve the session from your server, including when the customer visits the cancel URL.

const current = await checkoutRequest(
	`/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`,
);

if (
	current.id !== order.checkoutSessionId ||
	current.merchantOrderId !== order.id ||
	current.amount !== order.totalInMinorUnits ||
	current.currency !== order.currency
) {
	throw new Error('Checkout session does not match the order');
}

const paid = current.paymentStatus === 'successful';

Only when paid is true, record the payment and fulfill the order once in your server-side storage. If retrieval fails or the payment remains unresolved, retain the session ID for another status check. See Payment status for every state.