Checkout surface

A surface is the front-end mount point where the buyer enters their card. Every ShiftxPay surface is PSP-direct: the card is collected inside the PSP's own iframe and travels browser → PSP. Neither the SDK nor the gateway ever sees a PAN. This is the no-raw-card invariant — there is no surface that accepts raw card fields.

The Peach embedded widget

ShiftxPay accepts payments through a single surface, peach-embedded:

• peach-embedded — the Peach embedded widget. The SDK loads the merchant's Peach checkout script and mounts the widget, which renders the configured payment methods. The widget owns its own pay button and drives its own submit; completion is reported back to the SDK, which finalizes server-side.

Redirect-based methods — instant EFT, some wallets, and any 3-D Secure challenge — run inside the embedded flow. The buyer is taken to their bank or app and returns to your returnUrl; there is no separate redirect surface to configure. See 3-D Secure & redirects.

The surface is chosen for you

The merchant does not pick a surface in the SDK. mountCheckout reads the session's render hints (render.type), which the gateway derives from the merchant's active connector and its configured default surface. The SDK then mounts whichever surface the session asks for — so the same integration keeps working without change.

A merchant changes which surface their connector advertises with:

PATCH /v1/merchants/me/connectors/{cid}
Content-Type: application/json

{ "surface": "peach-embedded", "make_primary": true }

The chosen surface must be one the connector actually supports. The next session the merchant creates carries the updated render hints.

The surface at a glance

See Connectors for how a merchant's active connector is selected and configured.