Checkout Settings

Open Checkout in the Tapaya Platform. The page shows your Organization defaults and lists your organization's Checkout merchants. Select a merchant to open its settings page. Configure a merchant here before you integrate hosted Checkout or Embedded Checkout.

What each integration needs

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

Platform mode uses the organization Secret key from the API Keys page instead of a merchant checkout key.

Onboard a merchant for Checkout

Complete merchant onboarding with online payments selected, or both online and in-store payments. Online onboarding collects the shop website and online business details. A Checkout-only merchant does not need terminals.

Merchants requesting online payments appear automatically in Checkout merchants, including those awaiting approval. Creating a merchant record or checkout key does not grant online payment approval. An in-store approval alone does not enable Checkout.

The table shows the merchant's readiness:

Copy the Merchant token for platform mode, or select Settings to configure the merchant. Only organization administrators can edit Checkout settings.

Create merchant checkout keys

Under a merchant's Settings, Merchant checkout keys lists keys for that merchant's own backend. Enter a key name and select Create merchant key. Keys start with tapaya_test_ in sandbox and tapaya_live_ in production.

Copy the secret immediately. The Platform shows it only once and stores only a hash. 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.

Configure return destinations

Hosted Checkout returns the customer to your shop after payment or when they leave. Embedded payments do not use redirect URLs.

Return destinations belong to the credential that creates the session:

The two are never combined, and 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. If a session omits successUrl or cancelUrl and its credential has no default, creation is rejected.

In the section for your credential, add your shop to Allowed websites, then set the Default success URL and Default cancel URL. A shop might use:

• Allowed website: https://shop.example.
• Success URL: https://shop.example/checkout/return.
• Cancel URL: https://shop.example/checkout/cancel.

An allowed website is an origin: scheme, host, and optional port, without a path, query, or fragment. Matching uses the exact origin, including the port. Wildcards and hostname suffixes do not match. Use HTTPS for deployed shops; HTTP is accepted for local hosts.

A session can override the defaults with successUrl or cancelUrl when you create it. Overrides 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.

The Ready status describes merchant approval and gateway setup. It does not confirm your return URL configuration. Embedded payments do not need return URLs. Hosted sessions need defaults or explicit allowed URLs for the credential they use.

A visit to either return URL does not prove the payment outcome. Retrieve the session from your server before marking an order paid.

Set the customer-facing name

Customer-facing name is 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.

Wallets and appearance

Each merchant either selects Use organization wallets and appearance or sets its own. This switch does not affect return destinations, which follow the credential as described above. The merchant name and checkout keys always stay specific to the merchant.

The wallet and appearance Organization defaults apply to every merchant that uses them, and changes reach those merchants right away:

• Apple Pay and Google Pay. Cards are always enabled.
• Hide powered by Tapaya.
• Checkout color, a six-digit hex color such as #1380A5.
• Checkout logo, a PNG or WebP image up to 5 MB. Logo uploads and removals save immediately.

If no defaults have been saved, wallets are on, and the color and logo come from your organization branding.

A wallet button also depends on the customer's device and browser. Enabling a wallet does not guarantee that it appears everywhere. Live Google Pay requires a configured Google Pay merchant ID.

Hosted Checkout uses all of these settings. 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 embedded wallet buttons in your page as described in Embedded Checkout.

Use Checkout preview to review the branding and payment methods in desktop and mobile layouts.

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.

1. Open the merchant's Settings, then Apple Pay and Shop domains.
2. Select Add domain and download the verification file.
3. 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.
4. Enter the hostname, such as shop.example, and select Verify and add. Register www.shop.example separately if customers also use it.
5. Wait for the domain to show Active, then enable Apple Pay. Use Check now to diagnose a failing domain.

Keep the verification file available after registration. Each merchant needs its own domain registration, even when wallets and appearance come from organization defaults. A merchant needs a configured payment gateway before a domain can be registered.