Configuration

The FloPay SDK needs to know which environment to use — staging or production. This determines which billing API URL is used for all operations.

Programmatic Configuration (Recommended)

Call configureFlopay() once at app startup:

import { configureFlopay } from '@flopay/shared';
 
configureFlopay({ environment: 'production' });

Use 'staging' during development and 'production' in live environments.

Per-Component Override

For advanced use cases, you can override the billing API URL on individual components:

<FloPayCheckout
  sessionId={sessionId}
  billingApiUrl="https://custom-billing.example.com"
  onComplete={handleSuccess}
/>

Resolution Priority

The SDK resolves the billing API URL in this order:

1. Explicit billingApiUrl prop — highest priority, per-component override
2. configureFlopay() setting — global programmatic config
3. Fallback — staging (https://api.stage.flopay.com)

URL Mapping

Server-Side Usage

For server-side code (API routes, Node.js), use resolveBillingApiUrl():

import { resolveBillingApiUrl } from '@flopay/shared';
import { PaymentAPI } from '@flopay/js';
 
const api = new PaymentAPI(resolveBillingApiUrl());
const session = await api.getCheckoutSession(sessionId);

This reads the configured global environment or falls back to the staging billing API when none is set.