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

Use the Secret key from the API Keys page in the Tapaya Platform for your environment. Store it in TAPAYA_CHECKOUT_API_KEY on your server and send it with both Checkout calls:

Authorization: Bearer <secret-key>

This is the same organization credential called a Server Secret Token in the Platform API docs. Checkout requires the Bearer prefix. Other Platform API endpoints take the token directly, without that prefix. Keep the key on your server; see Checkout Security.

Which merchant receives the payment

Checkout uses the key's organization to find a merchant with the same registration number as the organization. Exactly one merchant must match, and that merchant must be active. If no merchant matches, multiple merchants match, or the matching merchant is inactive, authentication fails. In sandbox, an explicitly selected Checkout merchant can override registration-number matching, but must belong to the organization and be active.

Support for multiple merchants per organization is planned for a future release. The single-merchant matching requirement applies today.

Checkout session requests do not accept a merchantId to select another merchant. For reseller integrations, the backend also supports separately issued merchant-specific keys that identify one merchant directly. The Secret key from API Keys is sufficient for Checkout for your own organization when the matching requirements above are met.

Merchant onboarding and organization management use the Platform API.

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 '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.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"

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. These values have different purposes. 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.

Idempotency and errors

Creation requires a nonblank Idempotency-Key of at most 255 characters. A completed request with the same key and body replays its response. Reusing the key with a changed body returns HTTP 409. A request still being processed also returns HTTP 409.

Invalid totals, unsupported currencies, missing gateway configuration, disabled 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 until reconciliation.