How it works

ShiftxPay is a card-data-free payments gateway. It orchestrates payments across payment service providers (PSPs) on behalf of many merchants, but it is card-data-free by construction: a raw card never touches the gateway. The card always travels from the buyer's browser straight to the PSP, and ShiftxPay only ever holds PSP tokens, intent ids, and the card brand and last four digits.

The pieces

• Merchant server — your backend. It holds a secret API key and uses it to create checkout sessions and payments server-to-server. The API key never reaches the browser.
• Buyer browser + the SDK — @shiftx-mu/lite-checkout runs in the buyer's browser. It resolves a checkout session with a per-session secret and mounts the Peach embedded widget. The SDK never holds an API key.
• ShiftxPay gateway — the /v1 API. It creates intents with the PSP, records payments in a double-entry ledger, verifies inbound PSP webhooks, and fans out signed outbound webhooks to your server.
• PSP (Peach) — the provider that actually moves the money and receives the card. Peach is connected per-merchant, so each shop uses its own credentials and its own webhook signing key.

The lifecycle of a payment

Walking through the numbered steps:

1. Create the session. Your server calls POST /v1/checkout-sessions with your API key as a bearer token, passing the amount (in integer minor units), currency, and order metadata.
2. Gateway creates the intent. ShiftxPay selects the merchant's connector and asks the PSP to create a payment intent.
3. PSP returns the intent. The PSP hands back an intent id and a client_secret — the credential the browser will use to confirm the card.
4. Gateway returns the session. Your server receives the checkout session id (cs_...), a session_secret (cs_secret_...), and render hints describing which PSP surface to mount.
5. Hand off to the browser. Your page receives the session id and secret. The API key stays on your server; only the session secret crosses to the browser.
6. Resolve the session. The SDK calls GET /v1/checkout/{id}?secret=… to fetch the render hints (which Peach checkout script to load and the entity id).
7. Gateway returns render hints. ShiftxPay returns everything the SDK needs to draw the Peach embedded widget.
8. Buyer enters the card. The card is typed directly into the Peach embedded widget and confirmed against the PSP. The card data never reaches ShiftxPay.
9. PSP confirms in the browser. The PSP reports the in-browser result back to the SDK.
10. Confirm the session. The SDK calls POST /v1/checkout/{id}/confirm?secret=… to tell the gateway the buyer finished.
11. Gateway retrieves status. ShiftxPay asks the PSP for the authoritative intent status rather than trusting the browser.
12. PSP reports succeeded. The PSP confirms the outcome.
13. Gateway returns the result. The SDK receives { status: completed, payment_id } and can show the buyer a confirmation.
14. PSP webhook (parallel). Independently and asynchronously, the PSP sends a signed payment.succeeded webhook to the gateway. This is the backstop: if the buyer closes the tab before step 10, the webhook still drives the payment to its final state.
15. Outbound webhook. ShiftxPay fans out its own signed payment.succeeded webhook to your server, so your backend learns the outcome regardless of what the browser did.

The browser confirm path and the webhook path are independent. Treat the webhook as the source of truth for the final state of a payment, and use the browser result only to update the buyer's experience immediately.

Next

• Quickstart — from an API key to your first payment.
• How card data stays off your servers — why the gateway never sees a card.