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.

Add a merchant

An organization administrator selects Add merchant above the merchants table and chooses an active merchant from the organization.

In sandbox, adding a merchant assigns the shared Shift4 test account automatically. A merchant that already has its own Shift4 account keeps it. If no Shift4 account can be assigned, the merchant is not added.

The table shows each merchant's Merchant token, checkout keys, and last key use. Copy the token for platform mode. Select Settings to configure the merchant.

Remove from Checkout stops new payments for the merchant immediately, including unpaid payments already started. Its settings, payment history, and checkout keys are kept, so you can add the merchant again later.

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

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 merchants table flags a merchant that has merchant checkout keys but no valid Merchant API key redirects. Merchants without merchant keys are not flagged, because platform-mode sessions use the organization redirects.

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 effective checkout color as the card fields' focus accent (colorFocus). Variables your page passes in appearance.variables override it.

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