Gateway settingsCopy Anchor Link

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 modeCopy Anchor Link

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 the data of GET /v1/settings/gateways 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.

DashboardCopy Anchor Link

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 and a Session mode filter. A missing or legacy mode displays as Both.

Create, update, and listCopy Anchor Link

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 one page of gateways in the shared paginated envelope { data, page, limit, pages, total } and includes sessionMode on each item in data. page and limit select the page: limit defaults to 20 and accepts up to 100, so an account with more gateways than one page reads the remaining pages.

curl "https://api.flopay.com/v1/settings/gateways?page=1&limit=20&sessionMode=off_session" \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

GET /v1/settings/gateways?sessionMode= is an equality filter (both, on_session, or off_session). [in] accepts comma-separated values. sessionMode is also an allowed sort field, for example sort[asc]=sessionMode. A query parameter outside the documented filters is rejected with a 400.

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

Failover eligibilityCopy Anchor Link

cascadeEnabled says whether a gateway may receive a failover attempt after another gateway declines the same payment. When it is false, the gateway can still take a payment's first attempt, but it never receives a later failover attempt.

The field is optional on CreateGatewayBodyDto and UpdateGatewayBodyDto. Create requests that omit it default to false. On PATCH /v1/settings/gateways/:id, omit it to leave the current value unchanged. GatewayResponseDto always includes the resolved boolean; treat an older response without the field as off.

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 '{
    "cascadeEnabled": true
  }'

On GET /v1/settings/gateways, cascadeEnabled=true is an equality filter and cascadeEnabled is an allowed sort field, for example sort[asc]=cascadeEnabled.

DashboardCopy Anchor Link

In Settings > Gateways, create and edit forms show a Use for cascading (failover) checkbox under Session mode. It is unchecked by default for a new gateway. The gateway list shows a Failover column with On or Off.

Legacy Stripe Elements and wallet payments do not cascade. There is no separate merchant-facing Full-mode kill switch; per-gateway cascadeEnabled is the only control. New-card first attempts can be divided between processors by share; see Traffic split. See Failover boundaries.

Preference orderCopy Anchor Link

priority ranks your gateway accounts against each other. Lower ranks first, and a gateway created without one defaults to 0.

It is writable on create (POST /v1/settings/gateways) and update (PATCH /v1/settings/gateways/:id), and always present on read: GET /v1/settings/gateways/:id and each item in the data of GET /v1/settings/gateways include it on GatewayResponseDto. Sort the list by it with sort[asc]=priority.

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 '{
    "priority": 10
  }'

Preference is applied after gateways have been matched and found eligible for the payment context, so it decides between accounts that fit the payment equally well. It never promotes an account the payment context has already ruled out, and it never overrides a closer country or currency match. Equal context and equal priority fall back to the oldest gateway first, then to the lower gateway UUID, so the order is stable. See Gateway selection for the full decision.

A preference change applies to the next new payment. It does not re-route a payment already in flight, rewrite where past payments were processed, migrate provider-owned subscriptions, or skip a 3DS challenge. See Preference order.

DashboardCopy Anchor Link

In Settings > Gateways, the list is paginated and sorted by preference until you choose another sort. Edit preference order opens every gateway in first-to-last preference order with a Preference column and Move up and Move down actions on each row. The helper text is: Every gateway in first-to-last preference order. Preference is applied after gateways are matched and found eligible for the payment context.

Reordering is available only in that editor. The paginated list has no reorder controls, because one page, a filter, or a custom sort cannot express the full order.

Traffic splitCopy Anchor Link

trafficSplitPercent gives a gateway a relative share of new-card checkouts for its card processor. Use it to send part of your new-card traffic to a second processor.

It is a whole number from 0 to 100. It is optional on create (POST /v1/settings/gateways) and update (PATCH /v1/settings/gateways/:id), and always present on read: GET /v1/settings/gateways/:id and each item in the data of GET /v1/settings/gateways include it on GatewayResponseDto, as a number or null.

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 '{
    "trafficSplitPercent": 10
  }'

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 '{
    "trafficSplitPercent": null
  }'

Shares are relative weights. FloPay does not require them to total 100: 9 and 1 divide new-card checkouts exactly as 90 and 10 do. A gateway whose share is 0, null, or not set is fallback only while another card processor holds a positive share. When no competing processor holds a positive share, preference order applies.

Filter the list on the share with trafficSplitPercent=, or on a range with [gt], [gte], [lt], and [lte], for example GET /v1/settings/gateways?trafficSplitPercent[gte]=1. It is also a sort field: sort[desc]=trafficSplitPercent lists gateways without a share last.

The share applies only when a buyer enters a new card. See Traffic split for how a checkout is allocated, how country-specific accounts are handled, and how the split works with failover.

DashboardCopy Anchor Link

In Settings > Gateways, the create and edit forms include Traffic split (%). Leave it blank for no share. The gateway list shows a Traffic split column, where a blank or zero share reads Fallback only.

Once a gateway holds a share, the page shows New-card traffic split: the effective share of each card processor in each currency after the shares are normalized, with the account that represents each processor. It warns when a currency's shares do not total 100, when only one processor holds a share for a currency, when a processor holds a share for one currency but not another, and when a share sits on a gateway that cannot take new cards. Warnings never block a save.

RoutingCopy Anchor Link

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, buyer-started Auto checkout, hosted vault capture, and POST /v1/checkouts/sessions/setup.
• Merchant-initiated payments use gateways whose sessionMode is both or off_session. That pool covers 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.