Gateway settings

Gateway records tell FloPay which provider accounts may take a payment. Client owners and admins manage them in Settings > Gateways or through the settings/gateways REST API. Members cannot manage gateway settings. FloPay chooses which gateway to use on the server; there is no header, token, field, or SDK setting that lets a client select a gateway.

The published contract is CreateGatewayBodyDto, UpdateGatewayBodyDto, GatewayResponseDto, and nested GatewayDto.

Session mode

sessionMode says whether a gateway may serve buyer-present payments (on_session), merchant-initiated payments (off_session), or both.

The field is optional on create (POST /v1/settings/gateways) and update (PATCH /v1/settings/gateways/:id). Omitted values default to both. Unknown values are rejected.

Reads always present sessionMode. GET /v1/settings/gateways/:id and each item in GET /v1/settings/gateways (an unpaginated array) include it on GatewayResponseDto. Nested GatewayDto includes it too. Existing gateways that omit the field read as both.

sessionMode remains editable after connection validation. Provider, environment, and a Worldpay merchant code do not.

Dashboard

In Settings > Gateways, the create and edit forms include Session mode with Both, On-session, and Off-session. New gateways preselect Both. The helper text is: Both serves buyer-present checkout and merchant-initiated charges. On-session is checkout and setup only. Off-session is renewals, rebills, and saved-card charges.

The gateway list shows a Session mode column. A missing or legacy mode displays as Both.

Create, update, and list

Omit sessionMode when a single gateway should serve both pools:

curl -X POST https://api.flopay.com/v1/settings/gateways \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Card processing",
    "providerType": "stripe",
    "environment": "production",
    "currency": "YOUR_CURRENCY"
  }'

Set sessionMode when a second account should serve only one pool:

curl -X PATCH https://api.flopay.com/v1/settings/gateways/GATEWAY_ID \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionMode": "off_session"
  }'

GET /v1/settings/gateways returns every gateway as an unpaginated array and includes sessionMode on each item. Filter and sort on the v2 list: GET /v2/settings/gateways?sessionMode= is an equality filter (both, on_session, or off_session). [in] accepts comma-separated values. sessionMode is also an allowed v2 sort field.

Single-gateway merchants can leave Session mode on Both and do not need to set the field.

Routing

FloPay routes from pools of eligible gateways, not from explicit gateway pairs.

• Buyer-present payments use gateways whose sessionMode is both or on_session. That pool covers Full checkout, Confirm, hosted vault capture, and POST /v1/checkouts/sessions/setup.
• Merchant-initiated payments use gateways whose sessionMode is both or off_session. That pool covers Auto checkout, Flo renewals, rebills, and dunning, saved-payment charges, and POST /v1/payments one-off charges.
• Continuations (capture, void, refund, inquiry, replay) stay on the original gateway.

A both gateway serves either pool. When a pool has no eligible gateway, routing fails closed with zero provider call: Flo does not create the payment.

Worldpay merchants that hold a separate recurring merchant code register it as an off-session gateway. See Worldpay Corporate Gateway.