Tapaya

API Integration

Create and retrieve Checkout sessions from your backend over HTTP.

The Checkout API is a REST API for your backend. Create a Checkout session for each order, redirect the customer to it, then retrieve the session to confirm payment. All requests and responses are JSON.

On Node.js, use the @tapayadot/checkout SDK instead: it wraps these endpoints in typed create() and get() methods and reads TAPAYA_SECRET_KEY from the environment. The examples on this page read the key from TAPAYA_CHECKOUT_API_KEY.

Authentication

Authenticate every request with a key in the Authorization header. Call the API only from your server; see Checkout Security.

Authorization: Bearer <key>

The key you use sets the mode:

Merchant mode

Use a merchant checkout key when your backend serves one shop. Create it in Checkout settings: open the merchant and select Create merchant key.

Authorization: Bearer <merchant-checkout-key>
  • The key starts with tapaya_test_ in sandbox and tapaya_live_ in production, and always acts for its own merchant.
  • X-Tapaya-Merchant-Token is optional. If you send it, it must name the same merchant.
  • The key is shown once; Tapaya stores only a hash. To rotate it, create a new key, deploy it, then revoke the old one. Revoking a key does not affect other keys or client secrets already issued to browsers.

Platform mode

Use the organization Secret key when one backend acts for many merchants, such as a marketplace. Copy it from the API Keys page, and send 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 X-Tapaya-Merchant-Token returns 401.
  • The merchant must belong to the key's organization. Copy merchant tokens from the merchants table in Checkout settings. A merchant token is an identifier, not a secret.
  • The Platform API calls the same key a Server Secret Token. Checkout requires the Bearer prefix; other Platform API endpoints take the token without it.

Request bodies never take a merchantId. The key and token select the merchant.

Environments

SandboxProduction
API base URLhttps://api.sandbox.tapaya.comhttps://api.tapaya.com
Hosted Checkouthttps://checkout.sandbox.tapaya.comhttps://checkout.tapaya.com
KeysSandbox keys, with test cardsLive keys, with real payment methods

The examples read the base URL from TAPAYA_CHECKOUT_API_URL. To take payments in production, a merchant must complete onboarding, be approved for online payments, and have a payment gateway configured. Check readiness in Checkout settings.

Checkout sessions

A Checkout session is one hosted payment page for one order.

Create a Checkout session

Creates a session for an order and returns the URL of its payment page. Calculate the final total on your server, save the order with an idempotency key, then call this endpoint.

POST /merchant/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",
        "customer": { "email": "buyer@example.com" },
        "tax": 2100,
        "shipping": 605,
        "taxRate": 21,
        "successUrl": "https://shop.example/checkout/return",
        "cancelUrl": "https://shop.example/checkout/cancel"
    }'

Headers:

HeaderRequiredDescription
Authorization✓Bearer and a merchant checkout key or the organization Secret key.
X-Tapaya-Merchant-TokenPlatform modeThe merchant to act for. Optional with a merchant checkout key.
Idempotency-Key✓Up to 250 characters, not blank. See Idempotency and errors.

Parameters:

FieldTypeRequiredDescription
merchantOrderIdstring✓Your order ID, 1 to 200 characters. See One payment per order.
amountinteger✓Amount to charge, in minor units, including tax and shipping. 0 to 2,147,483,647. 0 saves a card without charging it, and requires savePaymentMethod: 'required', a customerReference, and no shippingOptions.
currencystring✓Three-letter ISO 4217 code in uppercase, such as EUR. The merchant must be enabled for it.
localestringLanguage of the payment page. Defaults to the browser language.
successUrlstringWhere to send the customer after payment. Overrides your default. Must match an allowed website.
cancelUrlstringWhere to send the customer if they cancel. Overrides your default. Must match an allowed website.
taxinteger or nullVAT included in amount, from 0 to amount. 0 shows "no VAT"; omit or null hides the row.
shippinginteger or nullShipping included in amount, from 0 to amount. 0 shows "free shipping"; omit or null hides the row.
taxRatenumberVAT rate for the whole order, such as 21 or 5.5. Not negative.
taxBreakdownarrayVAT per rate, for orders with several rates. Do not send with taxRate.
itemsarrayProducts to show on the page. Display only; they do not change amount.
customerobject✓Must contain email or phone. Name and addresses are optional.
customerCollectionobjectCollection policy for email, name, phone, and billingAddress: none, optional, or required each. Omit or null for merchant defaults. {} requests no additional fields. Supply the required email or phone in customer.
shippingOptionsobjectFixed delivery options, or quotes your server approves. See Customer details and shipping.
customerReferencestringWhen savingYour ID for the customer, unique within the merchant.
savePaymentMethodstringnone, optional, or required. With required, you confirm you already collected the customer's consent.
paymentMethodUsagestringWhen savingon_session or off_session. Omit when not saving.
savingTermsobjectYour consent text and an HTTPS terms url. text requires locale.
walletAgreementobjectApple Pay, off-sessionRecurring or automatic reload terms. See Save cards and charge later.

Tapaya charges amount exactly as sent. It never adds tax or shipping, calculates VAT from a rate, or totals items. A currency the merchant is not enabled for is rejected; see Supported Currencies.

Response:

{
    "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"
}
CodeDescription
200The session was created. A repeated request with the same key, body, and mode returns the same session.
409The key was reused with a different body or mode (API-0025), or the order is already paid or has a payment in progress.

Save id with your order, then redirect the customer to url with HTTP 303. Do not change the URL.

  • taxRate is returned only if you sent it.
  • The session accepts payments for 30 minutes. A payment submitted before then still completes.
  • Return URLs are fixed when the session is created: your successUrl and cancelUrl, or the defaults of the key you used. The organization Secret key uses the organization's return destinations; a merchant checkout key uses the merchant's. The two are never mixed.

Retrieve a Checkout session

Returns the current state of a session. Call it when the customer comes back to your successUrl or cancelUrl, and from a scheduled job for customers who never come back. Compare it with your order before you fulfill.

GET /merchant/checkout-sessions/{id}

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"

Returns the same fields as the create response, plus:

  • paymentReference: the latest payment attempt, or null before the first attempt. It does not mean the payment succeeded.
  • completedAt: when the payment succeeded, or null.
  • customer: the details the customer entered or confirmed.

Timestamps are ISO 8601.

status:

statusMeaning
openThe session accepts payment, or a submitted payment is still being confirmed.
completedThe session is finished. Read paymentStatus for the result.
expiredThe session no longer accepts payment: it timed out, or a newer session for the same order replaced it.

paymentStatus:

paymentStatusMeaning for the order
unpaidNo successful payment yet. The outcome may still be being confirmed.
successfulPaid. Check order ID, amount, and currency, then fulfill.
failedDeclined. The customer can try another card or wallet while the session is open.
cancelledThe payment was cancelled.
action_neededMore action is needed. Do not fulfill.

A declined card leaves the session open with paymentStatus: failed. While Tapaya confirms an uncertain outcome, the session stays open and unpaid; retrieve it again later. A customer landing on your cancelUrl only clicked the cancel link; it does not set paymentStatus to cancelled.

Fulfill only after this check

Fulfill only when paymentStatus is successful and the session's merchantOrderId, amount, and currency match your order. A redirect to your successUrl alone never proves payment.

One payment per order

Your server owns the order: its ID, prices, currency, and fulfillment. Tapaya owns the session and the payment result. Store the session id with the order, so you can retrieve the result even if the customer closes the browser.

Hosted and Embedded Checkout share one payment engine, so each merchantOrderId can be paid at most once. Order IDs are scoped to the merchant: two merchants can use the same ID, even in one organization.

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

The payment page loads and confirms the session through its own public endpoints, where the session ID acts as an access credential. Your backend confirms payment only through the authenticated endpoint above.

Idempotency and errors

POST /merchant/checkout-sessions requires an Idempotency-Key of up to 250 characters, not blank. Generate one per checkout attempt and store it with the order. For the same merchant:

You sendTapaya returns
The same key, body, and modeThe same session, with its current status and paymentStatus
The same key with a different body409, code API-0025
The same key and body with the other mode409, code API-0025, because each mode has its own return URLs
Invalid totals, an unsupported currency, a disallowed return URL, no configured gateway, or a merchant not set up for CheckoutAn error; no session is created

A timeout or network error means the outcome is unknown, not that the request failed. Retrieve the session to find out, and retry creation only with the same key and body. Receive checkout session webhooks even when the customer never returns. Keep retrieving unresolved sessions as a recovery path.

A declined card is a payment result on the session, not an HTTP error.

Saved cards and payments

These endpoints use the same authentication. See Save cards and charge later for request examples, and the Node.js SDK for typed methods.

EndpointDescription
GET /merchant/saved-payment-methodsList a customer's saved cards. Requires customerReference; optional limit, cursor, and wallet. Returns { data, nextCursor }.
GET /merchant/saved-payment-methods/{id}Retrieve a saved card and its consent record.
PATCH /merchant/saved-payment-methods/{id}Update the expiry date, cardholder name, or billing address. Returns 409 for a card saved through a wallet.
DELETE /merchant/saved-payment-methods/{id}Delete a saved card.
POST /merchant/paymentsCreate a payment with a new card, or charge a saved paymentMethodId. One unresolved payment per merchantOrderId; give each renewal or top-up its own order.
GET /merchant/payments/{id}Retrieve a payment, with its authorized, captured, and refunded amounts.
POST /merchant/payments/{id}/captureCapture all or part of a manual authorization. Runs once.
POST /merchant/payments/{id}/incrementIncrease an incremental authorization by amount.
POST /merchant/payments/{id}/cancelRelease an authorization, or cancel an unfinished customer action. A captured payment is refunded instead.
POST /merchant/payments/{id}/recoverRecover a charge, capture, increment, or release whose outcome is unknown, such as after a timeout. Replays the original request, within a limited window. Returns the payment.
POST /merchant/payments/{id}/refundsRefund a captured payment, in parts if needed, up to amountCaptured. For Hosted Checkout, {id} is the session's paymentReference.
GET /merchant/payments/{id}/refundsList a payment's refunds. Returns { data }.
GET /merchant/payments/{id}/refunds/{refundId}Retrieve a refund.
  • Idempotency: every write takes an Idempotency-Key of 1 to 255 printable ASCII characters, no spaces. Use a separate key per operation and reuse it after a lost response.
  • Payment status: ready, pending, action_required, authorized, successful, declined, or cancelled. These differ from a session's paymentStatus. authorized is a hold, not a charge; pending needs another read.
  • Refund status: pending, succeeded, or failed.
Missing something on this page?Request a feature. We attach this page so the team sees the context.