Tapaya

Checkout Security

The server-side rules that keep a Checkout integration safe, from key handling to verifying a payment before fulfillment.

Tapaya hosts the card fields, tokenization, card authentication, and charging, so your systems never handle raw card data. What stays with you is the server that creates payments and decides when an order is paid. These rules apply to both hosted Checkout and embedded payments.

For how Tapaya handles cardholder and personal data, see Data Protection & Privacy.

Keep keys on the server

  • Store your merchant checkout key or organization Secret key in server-side configuration only. Neither belongs in browser code, mobile app bundles, or source control. Only the publishable key and a payment's client secret reach the browser.
  • Call the merchant Checkout API from your server runtime. Do not run these requests in the customer's browser.
  • A merchant checkout key reaches only its merchant. Give a merchant's own backend that key, never your organization Secret key.
  • The organization Secret key has organization-wide privileges. In platform mode, send it with X-Tapaya-Merchant-Token on every request; the API checks that the merchant belongs to the key's organization. See Checkout authentication.
  • Merchant keys are shown once and stored only as a hash. Revoke a key you suspect is exposed, after creating its replacement.

Own the order on your server

  • Calculate the order total on your server and persist the order before creating a session or payment attempt.
  • Read amounts, currency, and order IDs from your stored order snapshot. Do not accept replacements sent by the browser.
  • For embedded payments, bind your prepare and submit endpoints to an authenticated checkout or a signed HTTP-only cookie, and validate the origin of mutation requests.

Verify before you fulfill

A browser redirect, a visit to your success URL, query parameters, return cookies, and browser messages are navigation data. None of them proves payment.

  • Retrieve the session from your server and compare its order reference, amount, currency, and payment status with the stored order.
  • Fulfill only when that check confirms hosted paymentStatus: successful or payment-resource status: successful. An authorized saved-card payment is an uncaptured hold. An HTTP 200 response alone does not prove payment.
  • Record fulfillment atomically, so repeated return visits or status checks cannot fulfill the same order twice.
  • If the session is still unpaid or retrieval fails, keep the session ID and check again with a bounded retry. Do not create another session because the first result is unknown: a new session for the order replaces the old one. Receive checkout session webhooks even when the customer never returns. Keep retrieving unresolved sessions as a recovery path.

Retry safely

  • Persist a unique idempotency key with the order before creating a session. If a request times out or its response is lost, retry with the same key and an unchanged body.
  • Do not generate a new key for an uncertain result. See Idempotency and errors for the replay rules.

Restrict redirect origins

  • Add only your own shop origins to Allowed websites in Checkout settings.
  • Use HTTPS for deployed shops. Per-session successUrl and cancelUrl overrides must still match a configured origin.

Protect saved methods and delivery approvals

  • Resolve customerReference from the authenticated customer. Check method ownership before listing, updating, deleting, or charging a saved method.
  • Collect consent before required saving or off-session charging. Keep returned consent evidence with your billing records.
  • Keep client secrets in memory and send them only to the authorized shopper. Never log or persist them.
  • Approve shipping revisions from your server's cart and delivery rules. Store the final approved amount and compare it during fulfillment.
  • Keep hosted shipping callback secrets server-only. Verify the signature against the exact raw body before parsing or pricing.

Reporting a security issue

If you suspect a vulnerability or a security incident, contact the security team as described in Contacts.

Missing something on this page?Request a feature. We attach this page so the team sees the context.