---
schema_version: "1"
id: 9722b57d44828ba1b95a57c8ed2bc4417c9423f1e534dc1fa1cdde766510b73b
title: Integrate Payment Gateways Using the Payment Gateway SPI
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/guides/payment-gateway-spi.md
canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/guide/payment-gateway-spi.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: a4c164a86be7f7ed49ca3711d7059e638f9d8345a04ef97d6d5b4ac92bb14e2c
products:
  - Point of Sale for Developers
  - Salesforce APIs
---
# 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.

**note:** For endpoint details, see [Payment Gateway SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/payment-spi?meta=Summary) in the Point of Sale reference documentation.

For a comprehensive list of Point of Sale APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Architecture

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

![Sequence diagram of a payment: the POS iOS App opens a WebSocket to the Payment SPI Server and receives a CONNECTED event, then POSTs a payment over REST (mTLS + HMAC). The proxy makes a gateway SDK call to the Payment Terminal, then streams real-time terminal events (card inserted, PIN entry, authorization progress) back to the client over the WebSocket while the cardholder interacts with the terminal. Finally, the terminal returns an authorization result to the proxy, which returns the final REST response to the client.](https://developer.salesforce.com/docs/media/retail-cloud/payment-gateway-spi-architecture.png)

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.

## Security Modes

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](https://developer.salesforce.com/docs/commerce/retail-cloud/references/payment-spi?meta=Summary).

## Date Format

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.

## Client Timeouts

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.

| Operation                | Timeout |
|--------------------------|---------|
| Initial connection       | 10s     |
| Payment                  | 120s    |
| Payment + recovery       | 300s    |
| Status query             | 30s     |
| Health check             | 5s      |
| Cancel / Void            | 30s     |
| Refund                   | 120s    |
| Gift Card Balance        | 30s     |
| Gift Card Operation      | 60s     |
| Gift Card Payment        | 120s    |
| Card Acquisition         | 120s    |
| Terminal Display         | 10s     |
| Terminal Input           | 120s    |
| PBL Create               | 30s     |
| PBL Expire               | 15s     |
| PBL Status Query         | 15s     |
| PBL Refund/Void          | 120s    |
| SAF Query                | 15s     |
| Offline Validation       | 30s     |
| Terminal Offline Status  | 5s      |