Tapaya

Checkout Settings

Check merchant approval and manage Checkout return destinations, wallets, branding, and keys in the Tapaya Platform.

Set up a merchant here before you integrate Hosted Checkout or Embedded Checkout. Open Checkout in the Tapaya Platform: 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

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

SettingHosted CheckoutEmbedded Checkout
Onboard the merchant until it is ReadyRequiredRequired
Merchant checkout keysMerchant modeMerchant mode
Return destinationsRequiredNot used
Customer-facing name, wallets, and appearanceOptionalOptional
Apple Pay shop domainsNot usedFor Apple Pay

Your credential decides which keys and return destinations apply:

You authenticate withModeKeys come from
A merchant checkout keyMerchant modeThe merchant's settings, below
Your organization Secret key with X-Tapaya-Merchant-TokenPlatform modeThe API Keys page

Not set here

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

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

StatusMeaningNext step
Merchant inactiveThe merchant account is inactive.Resolve the account status before accepting payments.
Pending approvalThe online payment processor has not approved the merchant.Complete onboarding and resolve any requested information.
No payment gatewayOnline payments are approved, but the merchant has no gateway configured.Contact Tapaya to complete gateway setup.
ReadyThe 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, or select Settings to configure the merchant.

Create merchant checkout keys

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

Open the merchant's Settings and find Merchant checkout keys.

Enter a key name and select Create merchant key.

Copy the secret right away and store it on your server.

The secret is shown only once

The Platform stores only a hash of the key, so it cannot show the secret again.

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

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:

CredentialConfigure underApplies to
Organization Secret key with X-Tapaya-Merchant-Token (platform mode)Organization defaults › Redirect URLsEvery merchant's sessions created by your platform backend
Merchant checkout keyThe merchant's settings › Merchant API key redirectsOnly sessions created with that merchant's keys

In the section for your credential:

Add your shop's origin to Allowed websites, such as https://shop.example.

Set the Default success URL, such as https://shop.example/checkout/return.

Set the Default cancel URL, such as https://shop.example/checkout/cancel.

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

A return visit is not proof of payment

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

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.

SettingWhat it does
Apple Pay, Google PayOffer the wallet. Cards are always enabled.
Hide powered by TapayaHide the "powered by Tapaya" mark.
Checkout colorAccent color, a six-digit hex such as #1380A5.
Checkout logoA 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.

Enabled is not always shown

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.

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.

Open the merchant's Settings, then Apple Pay and Shop domains.

Select Add domain and download the verification file.

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.

Enter the hostname, such as shop.example, and select Verify and add. Register www.shop.example separately if customers also use it.

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 its wallets and appearance come from the organization defaults.
Missing something on this page?Request a feature. We attach this page so the team sees the context.