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_ 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.

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

Your server owns the order reference, prices, currency, and fulfillment state. Tapaya owns the checkout session and gateway payment result.

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, repeating the key, body, and credential mode returns the same session with its current status and paymentStatus.

Reusing the key with a changed body or credential mode returns HTTP 409 with code API-0025. Switching between a merchant checkout key and the organization Secret key conflicts even when the body is identical, because each mode uses its own redirect settings.

Invalid totals, unsupported currencies, missing gateway configuration, a merchant not added to Checkout, or invalid redirect destinations reject creation. A card decline is a payment outcome, not proof that an HTTP request failed.

A network error or timeout leaves the payment outcome unknown. There are no Checkout webhooks yet: reconcile by retrieving the session from your server.