Gateway Management

FloPay processes payments through gateway records that hold your own Stripe and PayPal account credentials. This guide walks through connecting a new account end-to-end — creating a draft, registering the provider webhook manually, saving credentials, testing the connection, and activating — plus the operational rules for managing gateways afterwards.

Two surfaces expose the same workflow with the same names and lifecycle terminology:

• REST API — the settings/gateways operations (List Gateways, Get Gateway, Create Gateway, Update Gateway, Test Gateway Connection, Activate Gateway, Deactivate Gateway). The generated REST API docs are the endpoint reference; this page is the onboarding and operations guide.
• Dashboard — Settings → Gateways (/settings/gateways), with a per-gateway detail page for credentials, webhook setup, connection testing, and lifecycle actions.

Who Can Manage Gateways

• Client owners and admins manage their own client's gateways through both surfaces. Access is always scoped to the authenticated client — another client's gateway ids read as not found.
• Members have no access. API calls return 403 (Members cannot manage gateway settings.) and the dashboard hides the Settings area.
• Server-to-server callers authenticating with the client identifier as the Basic username and an active user-owned API token as the password have full access — the token is scoped to that client.
• FloPay superusers use the admin mirror (/v1/admin/settings/gateways, with an explicit target client) and select a client in the dashboard before listing or editing. The admin mirror is intentionally excluded from the public OpenAPI spec.

Accounts, Environments, and Multiple Gateways

One gateway record represents one provider account in one environment:

• Supported providers: stripe and paypal (providerType).
• Environments: stage and production (environment). stage corresponds to Stripe test mode and the PayPal sandbox; production corresponds to Stripe live mode and PayPal live. A test/sandbox account and a production account are always two separate gateway records — there is no in-place switch to production.
• Multiple accounts per provider are supported. A client can connect any number of distinct Stripe accounts and PayPal accounts, each as its own record with its own display name, currency, countries, and priority.
• Duplicates are rejected. Connecting the same provider account in the same environment twice fails with 409: Another gateway is already connected to provider account <id> in the <environment> environment.

During the first successful connection validation FloPay captures the canonical provider account identity (providerAccountId — the Stripe acct_… id, or the PayPal REST app client ID). From that point the gateway's identity — providerType, environment, and the connected account — is immutable. To target a different provider, environment, or account, create a new gateway.

Lifecycle

A gateway is always in one of three states (status):

Rules:

• Every new gateway starts as a draft. You can save a draft with no credentials at all and finish it later.
• Activation requires completeness plus a live provider check. All three credential fields — public identifier, secret credential, and webhook verification value — must be configured, and FloPay re-validates the stored credentials with the provider at activation time. Incomplete gateways fail with 409: Activation requires a complete provider connection. Missing: <fields>.
• Deactivation stops the gateway being used for new payments but keeps the record; only an active gateway can be deactivated.
• Reactivation runs the same validation path as activation — credentials are re-checked with the provider.
• Gateways are never deleted. There is no delete endpoint or dashboard action.

The Gateway Record

Public identifiers vs. write-only secrets

The publishableKey is a public identifier — Stripe publishable keys and PayPal client IDs are designed to appear in frontends, and read responses return them in full.

secretKey and webhookSigningSecret are write-only. You send them once; after that, read responses expose only metadata:

• secretKeyConfigured: true | false
• webhookSigningSecretConfigured: true | false
• updatedAt

There is no way to retrieve a secret after submission — not through the API, the dashboard, or FloPay support. The dashboard shows secret inputs as always-blank password fields with a "Configured — enter a new value to replace it." hint. If a secret is lost, generate a new one at the provider and submit the replacement.

To replace a credential, send the new value in an ordinary update request (PATCH on the API, or type into the blank secret field and save in the dashboard). Omitted credential fields keep their stored values. A credential-bearing update is atomic: FloPay validates the complete resulting credential set with the provider before saving anything — if validation fails, the stored configuration is untouched and you get a sanitized, actionable error.

The FloPay Webhook Callback URL

Phase 1 does not create provider webhooks automatically — you register them manually in each provider's dashboard, then give FloPay the verification value (Stripe signing secret or PayPal webhook ID).

FloPay exposes one shared inbound endpoint per provider:

• Stripe: https://<flopay-webhook-host>/webhooks/stripe
• PayPal: https://<flopay-webhook-host>/webhooks/paypal

The URL is per provider, not per gateway — deliveries are matched to your gateway by the account identity in the event payload, so every Stripe account you connect registers the same Stripe callback URL. The webhook host differs between FloPay's stage and production environments; copy the exact URL from the Webhook setup card on the gateway's dashboard detail page rather than constructing it by hand.

Connecting a Stripe Gateway

1. Create a draft

In the dashboard, open Settings → Gateways → Add gateway, choose provider Stripe and the environment, and create the draft. Via the API, POST /v1/settings/gateways (see API examples). Provider and environment stay editable while the draft is unvalidated.

2. Obtain the API keys

In the Stripe Dashboard → Developers → API keys, copy:

• the publishable key — pk_test_… (test mode) or pk_live_… (live mode) → FloPay's publishableKey
• the secret key — sk_test_… / sk_live_…, or a restricted key rk_test_… / rk_live_… with account read access → FloPay's secretKey

Match the environments. A stage gateway requires test-mode keys and a production gateway requires live-mode keys — mixed-mode credentials are rejected at validation with an explicit prefix error.

3. Register the webhook manually

1. In the Stripe Dashboard, open Developers → Webhooks and add a destination — in the same mode (test/live) as the keys.
2. Paste the FloPay Stripe callback URL from the gateway's Webhook setup card as the endpoint URL.
3. Subscribe the endpoint to the Stripe events FloPay consumes — the full list is in Stripe webhook events.
4. Copy the endpoint's signing secret (whsec_…) → FloPay's webhookSigningSecret.

4. Save the credentials

Submit publishableKey, secretKey, and webhookSigningSecret on the draft — in the dashboard form, or via PATCH. Because the request carries secrets, FloPay validates the full credential set with Stripe before saving and captures your Stripe account id (acct_…) as providerAccountId.

5. Test the connection

Run Test connection in the dashboard, or POST /v1/settings/gateways/:id/test. The test probes Stripe with the stored credentials without changing the gateway and reports success plus the account id, or a sanitized error.

6. Activate

Run Activate. FloPay checks completeness (all three credential fields), re-validates with Stripe, and moves the gateway to active. It is now eligible for payment processing.

Connecting a PayPal Gateway

1. Create a draft

Same as Stripe: Settings → Gateways → Add gateway with provider PayPal, or POST /v1/settings/gateways with "providerType": "paypal". Use stage for a sandbox app and production for a live app.

2. Obtain the REST app credentials

In the PayPal developer dashboard, open (or create) the REST API app for the matching environment — a sandbox app for a stage gateway, a live app for a production gateway — and copy:

• the client ID → FloPay's publishableKey
• the client secret → FloPay's secretKey

3. Register the webhook manually

1. On the same PayPal REST app, add a webhook.
2. Paste the FloPay PayPal callback URL from the gateway's Webhook setup card as the webhook URL.
3. Subscribe to the PayPal event types FloPay consumes — the full list is in PayPal webhook events.
4. After registration PayPal displays a webhook ID → FloPay's webhookSigningSecret.

4. Save the credentials

Submit publishableKey (client ID), secretKey (client secret), and webhookSigningSecret (webhook ID) on the draft. FloPay authenticates against PayPal sandbox or live as appropriate, verifies the webhook ID is registered on the account, and captures the canonical account identity.

5. Test the connection

Test connection / POST /v1/settings/gateways/:id/test probes PayPal with the stored credentials without mutating the gateway.

6. Activate

Activate checks completeness, re-validates against PayPal, and moves the gateway to active.

API Examples

All examples use client Basic authentication: $FLOPAY_CLIENT_ID is the client identifier and username, while $FLOPAY_API_TOKEN is the active user-owned API token and password. Owner/admin OAuth bearer tokens work the same way. Values like $FLOPAY_API_TOKEN and pk_live_PLACEHOLDER are placeholders — never paste real secrets into shared examples.

List and get

curl https://api.flopay.com/v1/settings/gateways \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

curl https://api.flopay.com/v1/settings/gateways/1c9e4a7e-5b2d-4f6a-9c3e-8d1f2b3a4c5d \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

A read response returns full public metadata but only …Configured booleans for secret fields:

{
  "id": "1c9e4a7e-5b2d-4f6a-9c3e-8d1f2b3a4c5d",
  "clientId": "7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "name": "UK Ltd Stripe (live)",
  "code": "gw_9f2c4d6e8a0b4c2d",
  "providerType": "stripe",
  "environment": "production",
  "status": "active",
  "currency": "GBP",
  "countries": ["GB", "IE"],
  "priority": 0,
  "providerAccountId": "acct_PLACEHOLDER",
  "publishableKey": "pk_live_PLACEHOLDER",
  "secretKeyConfigured": true,
  "webhookSigningSecretConfigured": true,
  "connectionValidatedAt": "2026-07-01T10:15:00.000Z",
  "createdAt": "2026-06-28T09:00:00.000Z",
  "updatedAt": "2026-07-01T10:15:00.000Z"
}

Create an incomplete draft

Credentials are optional at creation — this draft has none yet:

curl -X POST https://api.flopay.com/v1/settings/gateways \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UK Ltd Stripe (live)",
    "providerType": "stripe",
    "environment": "production",
    "currency": "GBP",
    "countries": ["GB", "IE"],
    "priority": 0
  }'

The response is a draft with providerAccountId: null, secretKeyConfigured: false, and webhookSigningSecretConfigured: false.

Update ordinary fields

Plain settings updates never touch credentials:

curl -X PATCH https://api.flopay.com/v1/settings/gateways/1c9e4a7e-5b2d-4f6a-9c3e-8d1f2b3a4c5d \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UK Ltd Stripe (GBP, live)",
    "countries": ["GB"],
    "priority": 1
  }'

Replace credentials

Credential fields are optional on the same PATCH — send only what you are replacing, and omitted secrets stay as they are. This request rotates the secret key and signing secret while keeping the publishable key:

curl -X PATCH https://api.flopay.com/v1/settings/gateways/1c9e4a7e-5b2d-4f6a-9c3e-8d1f2b3a4c5d \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secretKey": "sk_live_PLACEHOLDER",
    "webhookSigningSecret": "whsec_PLACEHOLDER"
  }'

FloPay validates the complete resulting credential set with the provider before saving. On success the response reflects only metadata — secretKeyConfigured: true, a fresh updatedAt — never the submitted values. On failure nothing is stored and the previous credentials remain in effect.

For PayPal the same fields carry the client ID (publishableKey), client secret (secretKey), and webhook ID (webhookSigningSecret).

Test the connection

curl -X POST https://api.flopay.com/v1/settings/gateways/1c9e4a7e-5b2d-4f6a-9c3e-8d1f2b3a4c5d/test \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

{
  "success": true,
  "providerAccountId": "acct_PLACEHOLDER",
  "error": null
}

The probe never mutates the gateway and never carries key material. On failure, success is false and error contains the sanitized provider message (see Troubleshooting).

Activate and deactivate

curl -X POST https://api.flopay.com/v1/settings/gateways/1c9e4a7e-5b2d-4f6a-9c3e-8d1f2b3a4c5d/activate \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

curl -X POST https://api.flopay.com/v1/settings/gateways/1c9e4a7e-5b2d-4f6a-9c3e-8d1f2b3a4c5d/deactivate \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

Both return the updated gateway record. Reactivating an inactive gateway uses the same activate endpoint and re-validates credentials with the provider.

Troubleshooting

Errors are sanitized — they describe what to fix without echoing credentials. Common cases:

Contacting support: share the gateway id, code, providerType, environment, status, timestamps, and the exact sanitized error text. Never share secret keys, client secrets, or signing secrets — FloPay support will never ask for them, and FloPay cannot read the ones you have stored.

Related

• REST API docs — generated OpenAPI reference for the settings/gateways operations
• Stripe webhook events — inbound Stripe events to subscribe the webhook endpoint to
• PayPal webhook events — inbound PayPal events to subscribe the webhook to
• Direct PayPal — how an active PayPal gateway changes checkout rendering
• Cascading Processing — how multiple active gateways are used at checkout