API Integration

Your backend creates a Checkout session for each order and retrieves it to verify the payment.

For Node.js, the @tapayadot/checkout SDK provides typed create() and get() methods for these endpoints. It reads TAPAYA_SECRET_KEY by default. The HTTP examples on this page pass TAPAYA_CHECKOUT_API_KEY explicitly.

Authentication

Every Checkout call is server-to-server and sends a key as a bearer token:

Authorization: Bearer <key>

Choose the mode that matches who runs the backend. Keep either key on your server; see Checkout Security.

Merchant mode

Use this when the backend serves one shop. Create a merchant checkout key in Checkout settings: open the merchant and select Create merchant key. The key starts with tapaya_test_ in sandbox or tapaya_live_ in production and resolves to exactly that merchant.

Authorization: Bearer <merchant-checkout-key>

X-Tapaya-Merchant-Token is optional in this mode. If you send it, it must name the same merchant.

The Platform shows the key once and stores only a hash. Create a replacement before revoking the old key to rotate it. Revoking a key does not affect other merchant keys, organization keys, or client secrets already issued to browsers.

Platform mode

Use this when one backend acts for many merchants, such as a marketplace or food delivery platform. Send the organization Secret key from the API Keys page and the merchant's token on every request:

Authorization: Bearer <secret-key>
X-Tapaya-Merchant-Token: <merchant-token>

There is no default merchant. A request without the header returns HTTP 401. The merchant must belong to the key's organization. Copy merchant tokens from the merchants table in Checkout settings. The token identifies the merchant; it is not a secret.

The organization Secret key is the same credential called a Server Secret Token in the Platform API docs. Checkout requires the Bearer prefix. Other Platform API endpoints take the token directly. Merchant onboarding and organization management use the Platform API.

Request bodies do not accept a merchantId.

Environments

Set TAPAYA_CHECKOUT_API_URL to the API origin for your environment. Both hosted and embedded payments are available in production. Each merchant must complete onboarding, receive online processor approval, and have a payment gateway configured. Check merchant readiness in Checkout settings. Use the returned hosted session URL unchanged.

Checkout Sessions

curl -X 'POST' "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" \
-H 'Idempotency-Key: order-1001-checkout-1' \
-d '{
        "merchantOrderId": "order-1001",
        "amount": 12100,
        "currency": "EUR",
        "tax": 2100,
        "shipping": 605,
        "taxRate": 21,
        "successUrl": "https://shop.example/checkout/return",
        "cancelUrl": "https://shop.example/checkout/cancel"
    }'

{
    "id": "cs_7Hq2x9LmR4",
    "merchantOrderId": "order-1001",
    "url": "https://checkout.sandbox.tapaya.com/c/cs_7Hq2x9LmR4",
    "status": "open",
    "paymentStatus": "unpaid",
    "amount": 12100,
    "currency": "EUR",
    "tax": 2100,
    "shipping": 605,
    "taxRate": 21,
    "taxBreakdown": [],
    "items": [],
    "expiresAt": "2026-07-15T12:30:00Z",
    "createdAt": "2026-07-15T12:00:00Z"
}

curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/cs_7Hq2x9LmR4" \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"

Order and payment ownership

A checkout session ID identifies a hosted checkout. Its merchantOrderId links it to your order, while paymentReference identifies the latest confirmation attempt. Store the session ID with the order so you can retrieve the result even if the customer closes the browser.

The hosted page uses separate public endpoints to load and confirm the session. Its session ID is an access credential for those endpoints. A merchant integration verifies payment through the authenticated merchant endpoint.

One payment per order

Hosted and Embedded Checkout share one payment engine. A merchant can have at most one successful payment per merchantOrderId. Order IDs are scoped to the merchant, so different merchants, even under one organization, can use the same IDs.

• Creating a session for an unpaid order replaces the previous unpaid session. The old URL reports expired and can no longer take payment.
• Creating a session for an order that is already paid, or has a payment in progress, returns HTTP 409.
• After a decline, the customer can try another card or wallet on the same session. Submitting the same card token again never charges twice.
• Tapaya sets the 3-D Secure policy and always attempts authentication.

Idempotency and errors

Creation requires a nonblank Idempotency-Key of at most 250 characters. For the same merchant:

A card decline is a payment outcome, not proof that an HTTP request failed.