# Checkout Settings (/online/integration/checkout_settings)



Set up a merchant here before you integrate [Hosted Checkout](/online/integration/hosted_checkout) or
[Embedded Checkout](/online/integration/embedded_checkout). Open **Checkout** in the
[Tapaya Platform](https://platform.tapaya.com/checkout-settings): the page shows your **Organization defaults** and a
list of your **Checkout merchants**. Select a merchant to open its settings.

Only organization administrators can edit Checkout settings.

## What each integration needs [#what-each-integration-needs]

Work through the settings your integration uses, top to bottom:

| Setting                                                                        | Hosted Checkout | Embedded Checkout |
| ------------------------------------------------------------------------------ | :-------------: | :---------------: |
| [Onboard the merchant](#onboard-a-merchant-for-checkout) until it is **Ready** |     Required    |      Required     |
| [Merchant checkout keys](#create-merchant-checkout-keys)                       |  Merchant mode  |   Merchant mode   |
| [Return destinations](#configure-return-destinations)                          |     Required    |      Not used     |
| [Customer-facing name, wallets, and appearance](#wallets-and-appearance)       |     Optional    |      Optional     |
| [Apple Pay shop domains](#register-apple-pay-shop-domains)                     |     Not used    |   For Apple Pay   |

Your credential decides which keys and return destinations apply:

| You authenticate with                                       | Mode                                                                | Keys come from                                                   |
| ----------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
| A merchant checkout key                                     | Merchant mode                                                       | The merchant's settings, [below](#create-merchant-checkout-keys) |
| Your organization Secret key with `X-Tapaya-Merchant-Token` | [Platform mode](/online/integration/api_integration#authentication) | The [API Keys page](https://platform.tapaya.com/api-keys/)       |

<Callout title="Not set here" type="info">
  * **Customer details:** supply `customer.email` or `customer.phone` when creating a hosted session.
    Embedded payments require an email or phone before confirmation.
    Use `customerCollection` for additional name or billing fields. Omit it or send `null` for merchant defaults;
    `{}` requests no additional fields. These settings do not replace the required email or phone.
  * **Saved cards:** merchants manage them on the merchant portal's **Saved cards** page. See
    [Save cards and charge later](/online/integration/saved_payment_methods#in-the-merchant-portal).
</Callout>

## Onboard a merchant for Checkout [#onboard-a-merchant-for-checkout]

Complete [merchant onboarding](/merchants/onboarding) with online payments selected, or both online and in-store
payments. Online onboarding collects the shop website and online business details.

* A merchant that requests online payments appears in **Checkout merchants** automatically, including while it waits
  for approval.
* A Checkout-only merchant does not need terminals.
* Creating a merchant record or a checkout key does not grant online payment approval.
* An in-store approval alone does not enable Checkout.

The merchants table shows each merchant's status:

| Status                 | Meaning                                                                            | Next step                                                    |
| ---------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Merchant inactive**  | The merchant account is inactive.                                                  | Resolve the account status before accepting payments.        |
| **Pending approval**   | The online payment processor has not approved the merchant.                        | Complete onboarding and resolve any requested information.   |
| **No payment gateway** | Online payments are approved, but the merchant has no gateway configured.          | Contact Tapaya to complete gateway setup.                    |
| **Ready**              | The merchant is active, online payments are approved, and a gateway is configured. | Configure keys, payment methods, and any hosted return URLs. |

From the table, copy the **Merchant token** for [platform mode](/online/integration/api_integration#authentication),
or select **Settings** to configure the merchant.

## Create merchant checkout keys [#create-merchant-checkout-keys]

A merchant checkout key lets that merchant's own backend call Checkout.

<Steps>
  <Step>
    Open the merchant's **Settings** and find **Merchant checkout keys**.
  </Step>

  <Step>
    Enter a key name and select **Create merchant key**.
  </Step>

  <Step>
    Copy the secret right away and store it on your server.
  </Step>
</Steps>

<Callout title="The secret is shown only once" type="warn">
  The Platform stores only a hash of the key, so it cannot show the secret again.
</Callout>

* Keys start with `tapaya_test_` in sandbox and `tapaya_live_` in production.
* A key works only for its merchant.
* Revoke a key to stop requests that use it. Other merchant keys and your organization keys stay valid.

See [Checkout authentication](/online/integration/api_integration#authentication).

## Configure return destinations [#configure-return-destinations]

Return destinations are where Hosted Checkout sends the customer after payment, or when they leave. Embedded card
fields do not use them. One exception: a customer-initiated saved-card payment needs an allowed `returnUrl` for its
hosted verification fallback.

Each credential has its own return destinations:

| Credential                                                                                                                   | Configure under                                          | Applies to                                                 |
| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| Organization Secret key with `X-Tapaya-Merchant-Token` ([platform mode](/online/integration/api_integration#authentication)) | **Organization defaults** › **Redirect URLs**            | Every merchant's sessions created by your platform backend |
| Merchant checkout key                                                                                                        | The merchant's settings › **Merchant API key redirects** | Only sessions created with that merchant's keys            |

In the section for your credential:

<Steps>
  <Step>
    Add your shop's origin to **Allowed websites**, such as `https://shop.example`.
  </Step>

  <Step>
    Set the **Default success URL**, such as `https://shop.example/checkout/return`.
  </Step>

  <Step>
    Set the **Default cancel URL**, such as `https://shop.example/checkout/cancel`.
  </Step>
</Steps>

**Rules:**

* **The two sets never mix.** Neither falls back to the other: a platform-mode session can return only to the
  organization's allowed websites, and a merchant-key session only to the merchant's.
* **No default, no session.** If a session omits `successUrl` or `cancelUrl` and its credential has no default, creation
  is rejected.
* **Overrides must be allowed.** A session can override the defaults with `successUrl` or `cancelUrl` when you
  [create it](/online/integration/api_integration#create-a-checkout-session). The override must still match an allowed
  website of the same credential. A platform serving merchants on different paths or subdomains usually passes both
  URLs on every session.
* **Origins match exactly.** An allowed website is an origin: scheme, host, and optional port, without a path, query, or
  fragment. Matching includes the port. Wildcards and hostname suffixes do not match.
* **HTTPS for deployed shops.** HTTP is accepted for local hosts.
* **Ready does not check this.** The **Ready** status covers merchant approval and gateway setup, not your return URLs.

<Callout title="A return visit is not proof of payment" type="warn">
  A visit to either return URL does not prove the payment outcome. Retrieve the session from your server before
  marking an order paid.
</Callout>

## Wallets and appearance [#wallets-and-appearance]

**Customer-facing name** is the merchant name shown at checkout and in payment wallets. Leave it blank to use the
merchant's legal name. It does not change the bank statement name.

Each merchant either selects **Use organization wallets and appearance** or sets its own. This switch does not affect
the merchant name, checkout keys, or return destinations: the name and keys stay specific to the merchant, and return
destinations follow the credential.

| Setting                       | What it does                                                            |
| ----------------------------- | ----------------------------------------------------------------------- |
| **Apple Pay**, **Google Pay** | Offer the wallet. Cards are always enabled.                             |
| **Hide powered by Tapaya**    | Hide the "powered by Tapaya" mark.                                      |
| **Checkout color**            | Accent color, a six-digit hex such as `#1380A5`.                        |
| **Checkout logo**             | A PNG or WebP image, up to 5 MB. Uploads and removals save immediately. |

* Changes to the **Organization defaults** reach every merchant that uses them right away.
* If no defaults have been saved, wallets are on, and the color and logo come from your organization branding.
* Use **Checkout preview** to review the branding and payment methods in desktop and mobile layouts.

Where each setting applies:

* **Hosted Checkout** uses all of them.
* **Embedded Checkout** uses the wallet settings, and the effective checkout color as the card fields' focus accent
  (`colorFocus`). Variables your page passes in `appearance.variables` override it. Enable the wallet buttons in your
  page as described in [Embedded Checkout](/online/integration/embedded_checkout#add-apple-pay-and-google-pay).

<Callout title="Enabled is not always shown" type="info">
  A wallet button also depends on the customer's device and browser, so an enabled wallet does not appear
  everywhere. Live Google Pay requires a configured Google Pay merchant ID.
</Callout>

## Register Apple Pay shop domains [#register-apple-pay-shop-domains]

For Apple Pay in Embedded Checkout, register each shop hostname where the wallet appears. Hosted Checkout runs on
Tapaya's domain. **Allowed websites** for hosted redirects do not register a domain for Apple Pay.

Before you start, the merchant needs a configured payment gateway.

<Steps>
  <Step>
    Open the merchant's **Settings**, then **Apple Pay** and **Shop domains**.
  </Step>

  <Step>
    Select **Add domain** and download the verification file.
  </Step>

  <Step>
    Serve the file unchanged, without an extension, at
    `https://shop.example/.well-known/apple-developer-merchantid-domain-association`. Use a valid HTTPS certificate, and
    serve the file directly without redirects.
  </Step>

  <Step>
    Enter the hostname, such as `shop.example`, and select **Verify and add**. Register `www.shop.example` separately if
    customers also use it.
  </Step>

  <Step>
    Wait for the domain to show **Active**, then enable Apple Pay. Use **Check now** to diagnose a failing domain.
  </Step>
</Steps>

* Keep the verification file available after registration.
* Each merchant needs its own domain registration, even when its wallets and appearance come from the organization
  defaults.
