# Quick Start Guide (/online/getting-started/quick_start_guide)





<div className="bg-background relative h-auto w-full overflow-hidden rounded-lg border mt-8">
  <FlickeringGrid className="absolute inset-0 z-0 size-full" squareSize="4" gridGap="6" maxOpacity="0.1" flickerChance="0.1" height="800" width="2000" />

  <CheckoutLifecycleDiagram />
</div>

Take online payments in three steps: your server starts a checkout for an order, the customer pays with a card,
Apple Pay, or Google Pay, and your server confirms the payment before you fulfill the order.

## Choose how customers pay [#choose-how-customers-pay]

<CheckoutComparison />

## Accept a payment [#accept-a-payment]

<div className="fd-steps [&_h3]:fd-step">
  ### Onboard your merchant [#onboard-your-merchant]

  Complete [merchant onboarding](/merchants/onboarding) with the online payments capability, or both online and in-store payments. A Checkout-only merchant does not need a terminal. Provide the shop website and online business details, and wait for processor approval. Creating a merchant record or an API key alone does not enable payments.

  Open **Checkout** in the [Tapaya Platform](https://platform.tapaya.com/checkout-settings). Merchants requesting online payments appear automatically, including those awaiting approval. Continue when the merchant is **Ready**.

  Open the merchant's **Settings**. Under **Merchant API key redirects**, add your shop to **Allowed websites** and set the default success and cancel URLs. A platform using the organization Secret key sets these under **Organization defaults** instead. The examples use `https://shop.example`. See [Checkout settings](/online/integration/checkout_settings) for wallets and branding.

  ### Store your key on the server [#store-your-key-on-the-server]

  Under the merchant's **Settings**, select **Create merchant key** and copy the `tapaya_test_…` key. It is shown only once. Keep it in server-side configuration only. It never belongs in browser code or source control.

  ```bash title=".env"
  TAPAYA_ENVIRONMENT=sandbox
  TAPAYA_CHECKOUT_API_URL=https://api.sandbox.tapaya.com
  TAPAYA_SECRET_KEY=tapaya_test_...
  ```

  The SDK reads `TAPAYA_SECRET_KEY` and `TAPAYA_ENVIRONMENT` automatically. The HTTP examples below use `TAPAYA_CHECKOUT_API_URL`. Load the variables into your server process; the SDK does not load `.env` files.

  Send the key as `Authorization: Bearer <key>`. A merchant key selects its merchant, so no other header is needed. A platform serving many merchants uses the organization Secret key instead and sends `X-Tapaya-Merchant-Token` on every request. See [Checkout authentication](/online/integration/api_integration#authentication).

  ### Create a Checkout session [#create-a-checkout-session]

  When the customer clicks **Checkout** in your shop, calculate the final total on your server, persist the order with a unique attempt key, and create a session. `merchantOrderId` is required, and an order can be paid only once. Amounts are in minor units, so `12100` is EUR 121.00.

  For Node.js 22.13.0 or newer, install the ESM SDK before using the **Node.js SDK** example:

  <CodeBlockTabs defaultValue="npm" groupId="package-manager">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        Bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```sh
      npm install @tapayadot/checkout
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```sh
      pnpm add @tapayadot/checkout
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```sh
      bun add @tapayadot/checkout
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  <CodeBlockTabs defaultValue="fetch" groupId="quick-start-server">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="fetch">
        HTTP (fetch)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="node">
        Node.js SDK
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="curl">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="fetch">
      ```js title="server/checkout.js"
      const response = await fetch(
        new URL('/merchant/checkout-sessions', process.env.TAPAYA_CHECKOUT_API_URL),
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}`,
            'Content-Type': 'application/json',
            'Idempotency-Key': order.checkoutAttemptKey,
          },
          body: JSON.stringify({
            merchantOrderId: order.id,
            amount: order.totalInMinorUnits,
            currency: order.currency,
            customer: { email: order.customer.email, phone: order.customer.phone },
            successUrl: 'https://shop.example/checkout/return',
            cancelUrl: 'https://shop.example/checkout/cancel',
          }),
        },
      );
      if (!response.ok) throw new Error(`Checkout failed (${response.status})`);
      const session = await response.json();
      ```
    </CodeBlockTab>

    <CodeBlockTab value="node">
      ```ts title="server/checkout.ts"
      import { Tapaya } from '@tapayadot/checkout';

      const tapaya = new Tapaya();
      const session = await tapaya.checkout.sessions.create(
      	{
      		merchantOrderId: order.id,
      		amount: order.totalInMinorUnits,
      		currency: order.currency,
      		customer: { email: order.customer.email, phone: order.customer.phone },
      		successUrl: 'https://shop.example/checkout/return',
      		cancelUrl: 'https://shop.example/checkout/cancel',
      	},
      	{ idempotencyKey: order.checkoutAttemptKey },
      );
      ```
    </CodeBlockTab>

    <CodeBlockTab value="curl">
      ```bash title="Terminal"
      curl --request POST "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \
        --header "Authorization: Bearer $TAPAYA_SECRET_KEY" \
        --header 'Content-Type: application/json' \
        --header 'Idempotency-Key: order-1001-checkout-1' \
        --data '{
          "merchantOrderId": "order-1001",
          "amount": 12100,
          "currency": "EUR",
          "customer": { "email": "buyer@example.com" },
          "successUrl": "https://shop.example/checkout/return",
          "cancelUrl": "https://shop.example/checkout/cancel"
        }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  If the request times out, retry with the **same** key and body. The API replays the original session instead of creating a second one.

  ### Redirect the customer [#redirect-the-customer]

  Save `session.id` with your order, then send the browser to `session.url` with HTTP 303. Use the URL exactly as returned.

  ```ts
  // First persist session.id as the order's checkoutSessionId.
  return Response.redirect(session.url, 303);
  ```

  Tapaya shows the order summary and secure payment form, and handles tokenization, 3D Secure, and charging. After a decline, the customer can try another card on the same page. Sessions accept new payments for 30 minutes.

  ### Verify the payment on your server [#verify-the-payment-on-your-server]

  When the customer lands on your success or cancel URL, retrieve the session with your Secret key and compare it with the stored order. A redirect alone never proves payment.

  <CodeBlockTabs defaultValue="fetch" groupId="quick-start-status">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="fetch">
        HTTP (fetch)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="node">
        Node.js SDK
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="fetch">
      ```js title="server/return.js"
      const response = await fetch(
        new URL(
          `/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`,
          process.env.TAPAYA_CHECKOUT_API_URL,
        ),
        { headers: { Authorization: `Bearer ${process.env.TAPAYA_SECRET_KEY}` } },
      );
      if (!response.ok) throw new Error(`Status check failed (${response.status})`);
      const current = await response.json();
      ```
    </CodeBlockTab>

    <CodeBlockTab value="node">
      ```ts title="server/return.ts"
      import { Tapaya } from '@tapayadot/checkout';

      const tapaya = new Tapaya();
      const current = await tapaya.checkout.sessions.get(order.checkoutSessionId);
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  For either integration, compare the result with the stored order before fulfilling it:

  ```ts
  const matches =
    current.id === order.checkoutSessionId &&
    current.merchantOrderId === order.id &&
    current.amount === order.totalInMinorUnits &&
    current.currency === order.currency;

  if (matches && current.paymentStatus === 'successful') {
    await fulfillOnce(order); // idempotent, safe on repeated visits
  }
  ```

  If the status is still `unpaid` or retrieval fails, keep the session ID and check again. Receive [checkout session webhooks](/webhooks/events#checkout-sessions) even when the customer never returns. Keep retrieving unresolved sessions as a recovery path.
</div>

## Go live [#go-live]

1. Complete production [merchant onboarding](/merchants/onboarding) with online payments, or both online and in-store payments. Provide the shop website and online business details. An existing in-store merchant still needs online processor approval.

2. Check that the merchant is **Ready** in [Checkout settings](/online/integration/checkout_settings). This requires an active merchant, online processor approval, and a configured live gateway.

3. Create a production merchant checkout key, or use your production organization Secret key with the merchant token. Keep live credentials on your server.

4. Set the production API origin and environment. Replace the sandbox configuration in your deployment:

   ```bash title="Production server configuration"
   TAPAYA_ENVIRONMENT=production
   TAPAYA_CHECKOUT_API_URL=https://api.tapaya.com
   TAPAYA_SECRET_KEY=tapaya_live_...
   ```

   The HTTP examples use `TAPAYA_CHECKOUT_API_KEY`; set it to your live key as well. Use the session URL exactly as returned. Production hosted pages open on `https://checkout.tapaya.com`.

5. Configure your production return URLs for Hosted Checkout. For embedded Apple Pay, register each shop domain and host its verification file. Live Google Pay requires a configured Google Pay merchant ID.

6. Complete the [QA Checklist](/online/getting-started/checklist), including server verification and the production job that checks unresolved payments. Use real payment methods in production. Sandbox test cards are for sandbox only.

## Next steps [#next-steps]

<Cards>
  <Card title="Testing" href="/online/getting-started/testing" description="Test cards for success, decline, and 3D Secure on the sandbox gateway." />

  <Card title="Hosted Checkout" href="/online/integration/hosted_checkout" description="The complete server guide, with error handling and retries for each approach." />

  <Card title="Node.js SDK" href="/online/integration/node_sdk" description="Client options, session methods, retries, and typed errors." />

  <Card title="API Integration" href="/online/integration/api_integration" description="Line items, tax breakdowns, customer details, and every session status." />

  <Card title="Checkout settings" href="/online/integration/checkout_settings" description="Wallets, branding, and return destinations in the Tapaya Platform." />

  <Card title="Embedded Checkout" href="/online/integration/embedded_checkout" description="Mount secure card fields in your own checkout page and submit from your own Pay button." />
</Cards>
