# API Integration (/online/integration/api_integration)





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](/online/integration/node_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 [#authentication]

Authenticate every request with a key in the `Authorization` header. Call the API only from your server; see
[Checkout Security](/online/security/checkout_security).

```http
Authorization: Bearer <key>
```

The key you use sets the mode:

<Cards>
  <VisualCard title="Merchant mode" visual="<Store />" href="#merchant-mode" description="One shop. A merchant checkout key, no extra header." />

  <VisualCard title="Platform mode" visual="<Building2 />" href="#platform-mode" description="Many merchants. The organization Secret key, plus a merchant token on every request." />
</Cards>

### Merchant mode [#merchant-mode]

Use a **merchant checkout key** when your backend serves one shop. Create it in
[Checkout settings](/online/integration/checkout_settings#create-merchant-checkout-keys): open the merchant and select
**Create merchant key**.

```http
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 [#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](https://platform.tapaya.com/api-keys/), and send the merchant's token on every request:

```http
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](/online/integration/checkout_settings). A merchant token is an identifier, not a secret.
* The [Platform API](/platform-api#authentication) 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 [#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](/online/getting-started/testing) | 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](/merchants/onboarding), be approved for online payments, and have a payment gateway configured.
Check readiness in [Checkout settings](/online/integration/checkout_settings).

## Checkout sessions [#checkout-sessions]

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

<div className="fd-steps [&_h3]:fd-step">
  ### Create a Checkout session [#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`

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      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"
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  **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](#idempotency-and-errors). |

  **Parameters:**

  | Field                | Type                | Required               | Description                                                                                                                                                                                                                               |
  | -------------------- | ------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `merchantOrderId`    | `string`            | ✓                      | Your order ID, 1 to 200 characters. See [One payment per order](#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](/online/integration/customer_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](/online/integration/saved_payment_methods).                                                                                                                        |

  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](/merchants/supported_currencies).

  <Accordions>
    <Accordion title="taxBreakdown entries">
      Each entry has a `taxRate` (number) and a `tax` (integer), both not negative. Rates must be unique, and the
      `tax` values must add up to the top-level `tax`.

      ```json
      {
          "amount": 22650,
          "currency": "EUR",
          "tax": 2650,
          "shipping": 605,
          "taxBreakdown": [
              { "taxRate": 21, "tax": 2100 },
              { "taxRate": 5.5, "tax": 550 }
          ]
      }
      ```
    </Accordion>

    <Accordion title="items entries">
      Each item requires `reference`, `name`, `description`, `quantity`, and `unitAmount`. Text fields are not
      blank, `quantity` is a positive integer, and `unitAmount` is a non-negative integer in minor units.
      `imageUrl` is optional. When set, it is a URL. Omit it or send `null` for an item without an image, and
      the session returns `imageUrl: null`.
    </Accordion>

    <Accordion title="customer fields">
      `customer` accepts `email`, `name`, `phone`, `billingAddress`, and `shippingAddress`. Supply at least one
      nonblank `email` or `phone` when creating a hosted session. Otherwise, the API returns HTTP 400 with
      "Customer email or phone number is required." Name and addresses are optional, including each address
      field, so a billing address can be just a postal code and country.

      | Field                    | Limit or format                                         |
      | ------------------------ | ------------------------------------------------------- |
      | `email`                  | Email address, up to 254 characters.                    |
      | `name`, `line1`, `line2` | Up to 200 characters each.                              |
      | `phone`                  | Up to 30 characters.                                    |
      | `city`, `state`          | Up to 100 characters each.                              |
      | `postalCode`             | Up to 20 characters.                                    |
      | `country`                | Two-letter ISO country code in uppercase, such as `CZ`. |

      Address text you send must not be blank. Tapaya passes these details to the payment gateway for risk
      checks. Retrieving the session returns the accepted details in `customer`; the create response may omit
      them.
    </Accordion>
  </Accordions>

  **Response:**

  ```json
  {
      "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.

  * `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](/online/integration/checkout_settings#configure-return-destinations); a merchant
    checkout key uses the merchant's. The two are never mixed.

  ### Retrieve a Checkout session [#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}`

  <CodeBlockTabs defaultValue="curl" groupId="http-client">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="curl">
      ```bash
      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"
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  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`:**

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

  <a id="payment-status" />

  **`paymentStatus`:**

  | `paymentStatus`                                 | Meaning for the order                                                              |
  | ----------------------------------------------- | ---------------------------------------------------------------------------------- |
  | <Badge variant="info">unpaid</Badge>            | No successful payment yet. The outcome may still be being confirmed.               |
  | <Badge variant="success">successful</Badge>     | Paid. Check order ID, amount, and currency, then fulfill.                          |
  | <Badge variant="error">failed</Badge>           | Declined. The customer can try another card or wallet while the session is `open`. |
  | <Badge variant="warning">cancelled</Badge>      | The payment was cancelled.                                                         |
  | <Badge variant="warning">action\_needed</Badge> | 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`.

  <Callout title="Fulfill only after this check" type="warn">
    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.
  </Callout>
</div>

## One payment per order [#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](/online/integration/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 [#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](/webhooks/events#checkout-sessions) 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 [#saved-cards-and-payments]

These endpoints use the same authentication. See [Save cards and charge later](/online/integration/saved_payment_methods)
for request examples, and the [Node.js SDK](/online/integration/node_sdk#payments) 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-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`.
