Quick Start Guide

Onboard your merchant

Complete merchant onboarding with the online payments capability, or both online and in-store payments. A Checkout-only merchant does not need a terminal. Provide the shop website and online business details, and wait for processor approval. Creating a merchant record or an API key alone does not enable payments.

Open Checkout in the Tapaya Platform. Merchants requesting online payments appear automatically, including those awaiting approval. Continue when the merchant is Ready.

Open the merchant's Settings. Under Merchant API key redirects, add your shop to Allowed websites and set the default success and cancel URLs. A platform using the organization Secret key sets these under Organization defaults instead. The examples use https://shop.example. See Checkout settings for wallets and branding.

Store your key on the server

Under the merchant's Settings, select Create merchant key and copy the tapaya_test_… key. It is shown only once. 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=tapaya_test_...

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 the key as Authorization: Bearer <key>. A merchant key selects its merchant, so no other header is needed. A platform serving many merchants uses the organization Secret key instead and sends X-Tapaya-Merchant-Token on every request. See Checkout authentication.

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. merchantOrderId is required, and an order can be paid only once. 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. After a decline, the customer can try another card on the same page. Sessions accept new payments for 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 still unpaid or retrieval fails, keep the session ID and check again. There are no webhooks yet, so run a reconciliation job for customers who close the tab before returning.