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:
| Setting | Hosted Checkout | Embedded Checkout |
|---|---|---|
| Onboard the merchant until it is Ready | Required | Required |
| Merchant checkout keys | Merchant mode | Merchant mode |
| Return destinations | Required | Not used |
| Customer-facing name, wallets, and appearance | Optional | Optional |
| 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 |
Your organization Secret key with X-Tapaya-Merchant-Token | Platform mode | The API Keys page |
Not set here
- Customer details: supply
customer.emailorcustomer.phonewhen creating a hosted session. Embedded payments require an email or phone before confirmation. UsecustomerCollectionfor additional name or billing fields. Omit it or sendnullfor 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:
| 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, 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 andtapaya_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.
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) | 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:
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
successUrlorcancelUrland its credential has no default, creation is rejected. - Overrides must be allowed. A session can override the defaults with
successUrlorcancelUrlwhen 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.
| 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 inappearance.variablesoverride 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.