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
One shop. A merchant checkout key, no extra header.
Platform mode
Many merchants. The organization Secret key, plus a merchant token on every request.
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 andtapaya_live_in production, and always acts for its own merchant. X-Tapaya-Merchant-Tokenis 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-Tokenreturns401. - 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
Bearerprefix; other Platform API endpoints take the token without it.
Request bodies never take a merchantId. The key and token select the merchant.
Environments
| Sandbox | Production | |
|---|---|---|
| API base URL | https://api.sandbox.tapaya.com | https://api.tapaya.com |
| Hosted Checkout | https://checkout.sandbox.tapaya.com | https://checkout.tapaya.com |
| Keys | Sandbox keys, with test cards | Live 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:
| Header | Required | Description |
|---|---|---|
Authorization | ✓ | Bearer and a merchant checkout key or the organization Secret key. |
X-Tapaya-Merchant-Token | Platform mode | The merchant to act for. Optional with a merchant checkout key. |
Idempotency-Key | ✓ | Up to 250 characters, not blank. See Idempotency and errors. |
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
merchantOrderId | string | ✓ | Your order ID, 1 to 200 characters. See One payment per order. |
amount | integer | ✓ | 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. |
currency | string | ✓ | Three-letter ISO 4217 code in uppercase, such as EUR. The merchant must be enabled for it. |
locale | string | Language of the payment page. Defaults to the browser language. | |
successUrl | string | Where to send the customer after payment. Overrides your default. Must match an allowed website. | |
cancelUrl | string | Where to send the customer if they cancel. Overrides your default. Must match an allowed website. | |
tax | integer or null | VAT included in amount, from 0 to amount. 0 shows "no VAT"; omit or null hides the row. | |
shipping | integer or null | Shipping included in amount, from 0 to amount. 0 shows "free shipping"; omit or null hides the row. | |
taxRate | number | VAT rate for the whole order, such as 21 or 5.5. Not negative. | |
taxBreakdown | array | VAT per rate, for orders with several rates. Do not send with taxRate. | |
items | array | Products to show on the page. Display only; they do not change amount. | |
customer | object | ✓ | Must contain email or phone. Name and addresses are optional. |
customerCollection | object | Collection 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. | |
shippingOptions | object | Fixed delivery options, or quotes your server approves. See Customer details and shipping. | |
customerReference | string | When saving | Your ID for the customer, unique within the merchant. |
savePaymentMethod | string | none, optional, or required. With required, you confirm you already collected the customer's consent. | |
paymentMethodUsage | string | When saving | on_session or off_session. Omit when not saving. |
savingTerms | object | Your consent text and an HTTPS terms url. text requires locale. | |
walletAgreement | object | Apple Pay, off-session | Recurring 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"
}| Code | Description |
|---|---|
200 | The session was created. A repeated request with the same key, body, and mode returns the same session. |
409 | The 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.
taxRateis 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
successUrlandcancelUrl, 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, ornullbefore the first attempt. It does not mean the payment succeeded.completedAt: when the payment succeeded, ornull.customer: the details the customer entered or confirmed.
Timestamps are ISO 8601.
status:
status | Meaning |
|---|---|
open | The session accepts payment, or a submitted payment is still being confirmed. |
completed | The session is finished. Read paymentStatus for the result. |
expired | The session no longer accepts payment: it timed out, or a newer session for the same order replaced it. |
paymentStatus:
paymentStatus | Meaning for the order |
|---|---|
| unpaid | No successful payment yet. The outcome may still be being confirmed. |
| successful | Paid. Check order ID, amount, and currency, then fulfill. |
| failed | Declined. The customer can try another card or wallet while the session is open. |
| cancelled | The payment was cancelled. |
| action_needed | More 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
expiredand 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 send | Tapaya returns |
|---|---|
| The same key, body, and mode | The same session, with its current status and paymentStatus |
| The same key with a different body | 409, code API-0025 |
| The same key and body with the other mode | 409, 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 Checkout | An 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.
| Endpoint | Description |
|---|---|
GET /merchant/saved-payment-methods | List 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/payments | Create 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}/capture | Capture all or part of a manual authorization. Runs once. |
POST /merchant/payments/{id}/increment | Increase an incremental authorization by amount. |
POST /merchant/payments/{id}/cancel | Release an authorization, or cancel an unfinished customer action. A captured payment is refunded instead. |
POST /merchant/payments/{id}/recover | Recover 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}/refunds | Refund a captured payment, in parts if needed, up to amountCaptured. For Hosted Checkout, {id} is the session's paymentReference. |
GET /merchant/payments/{id}/refunds | List a payment's refunds. Returns { data }. |
GET /merchant/payments/{id}/refunds/{refundId} | Retrieve a refund. |
- Idempotency: every write takes an
Idempotency-Keyof 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, orcancelled. These differ from a session'spaymentStatus.authorizedis a hold, not a charge;pendingneeds another read. - Refund
status:pending,succeeded, orfailed.