Quick Start Guide

Enable Checkout for your merchant

Open Settings > Checkout in the Tapaya Platform and turn on Enable Checkout. Set the default success and cancel URLs, and add your shop's origin to Allowed redirect origins. The examples use https://shop.example.

Upload your logo and pick a checkout color while you are there. See Checkout settings for every option.

Store your Secret key on the server

Copy or generate a Secret key on the API Keys page for your environment. This is the same organization credential called a Server Secret Token in the Platform API docs. Keep it in server-side configuration only. It never belongs in browser code or source control.

TAPAYA_ENVIRONMENT=sandbox
TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com
TAPAYA_SECRET_KEY=your-secret-key

The SDK reads TAPAYA_SECRET_KEY and TAPAYA_ENVIRONMENT automatically. The HTTP examples below use TAPAYA_CHECKOUT_API_URL. Load the variables into your server process; the SDK does not load .env files.

Send this key as Authorization: Bearer <secret-key> when calling Checkout. The API selects your merchant from the organization associated with the key. See Checkout authentication for merchant matching requirements.

Create a Checkout session

When the customer clicks Checkout in your shop, calculate the final total on your server, persist the order with a unique attempt key, and create a session. Amounts are in minor units, so 12100 is EUR 121.00.

For Node.js 22.13.0 or newer, install the ESM SDK before using the Node.js SDK example:

npm install @tapayadot/checkout

const response = await fetch(
  new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL),
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`,
      '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',
    }),
  },
);
if (!response.ok) throw new Error(`Checkout failed (${response.status})`);
const session = await response.json();

If the request times out, retry with the same key and body. The API replays the original session instead of creating a second one.

Redirect the customer

Save session.id with your order, then send the browser to session.url with HTTP 303. Use the URL exactly as returned.

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

Tapaya shows the order summary and secure payment form, and handles tokenization, 3D Secure, and charging. Sessions expire after 30 minutes.

Verify the payment on your server

When the customer lands on your success or cancel URL, retrieve the session with your Secret key and compare it with the stored order. A redirect alone never proves payment.

const response = await fetch(
  new URL(
    `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`,
    process.env.TAPAYA_CHECKOUT_API_URL,
  ),
  { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } },
);
if (!response.ok) throw new Error(`Status check failed (${response.status})`);
const current = await response.json();

For either integration, compare the result with the stored order before fulfilling it:

const matches =
  current.id === order.checkoutSessionId &&
  current.merchantOrderId === order.id &&
  current.amount === order.totalInMinorUnits &&
  current.currency === order.currency;

if (matches && current.paymentStatus === 'successful') {
  await fulfillOnce(order); // idempotent, safe on repeated visits
}

If the status is unresolved or retrieval fails, keep the session ID and check again. Run a reconciliation job for customers who close the tab before returning.