Integrate Payment Gateways Using the Payment Gateway SPI

Point of Sale’s Payment Gateway SPI lets you integrate third-party payment gateway terminals (for example, Worldpay or Stripe Terminal) with POS through a store-local proxy server. Implement the SPI on a proxy that runs on the store’s local network and acts as an intermediary between the POS iOS client and the payment gateway terminals. The proxy handles terminal communication, gateway protocol translation, and real-time event streaming so that new gateway integrations can be added without modifying the POS iOS application.

This diagram shows a payment for a client that uses the WebSocket channel.

The proxy exposes two channels that run side by side:

• REST over mTLS + HMAC-SHA256 — the command channel. The POS iOS client uses this to start, cancel, and query transactions. The REST response is the source of truth for a transaction’s outcome.
• WebSocket — the event channel. Long-lived and optional. The client uses events to render real-time UI updates as the cardholder interacts with the terminal (for example, CARD_INSERTED, PIN_ENTRY_STARTED, AUTHORIZATION_APPROVED).

The client generates a transactionId (UUID v4) per payment and uses it as the correlation ID across the WebSocket stream, the REST call, and any follow-up operations (cancel, void, capture, status query).

The payment flow, when the client uses the WebSocket channel:

1. The client opens a WebSocket to WSS /events?transactionId={transactionId} and waits for a CONNECTED event.
2. The client calls POST /payment with the same transactionId.
3. The proxy drives the terminal and streams events back over the WebSocket.
4. The proxy returns the final authorization result in the REST response.

The WebSocket channel is optional — support clients that skip it and rely on the REST response alone.

The proxy supports two security modes:

• Secure mode (production): Requires mTLS transport and HMAC-SHA256 request signing.
• Simple mode (testing only): No mTLS and no HMAC. Self-signed certificates are accepted.

For HMAC message format and required headers, see the Security section of the Payment Gateway SPI reference.

All date and time fields use ISO 8601 format. The proxy server must accept both:

• Standard format: 2026-03-12T14:04:06Z
• Fractional seconds: 2026-03-12T14:04:06.206Z

The server should return dates with fractional seconds for maximum precision.

The POS iOS client enforces per-operation timeouts. If the proxy doesn’t respond within the window listed below, the client treats the request as failed.