PaymentAPI

PaymentAPI

Client-side payment API service. All methods call the billing API endpoints that the checkout backend exposes.

class PaymentAPI {
  constructor(billingApiUrl: string)
}

getCheckoutSession

Fetch a raw checkout session by ID.

async getCheckoutSession(
  checkoutSessionId: string
): Promise<BillingResponse<RawCheckoutSession>>

Returns: Promise<BillingResponse<RawCheckoutSession>> -- the raw billing API response.

Throws: FloPayError with type 'api_error' if the request fails.

Endpoint: GET /v1/checkouts/sessions/{checkoutSessionId}

getUnifiedCheckoutSession

Fetch and normalize a checkout session. Reads the backend's gateways map (see CheckoutGatewaysDto) and wraps the session in a NormalizedCheckoutSession. gateways.stripe populates data.stripe, and gateways.paypal populates data.paypal for the direct PayPal flow.

async getUnifiedCheckoutSession(
  checkoutSessionId: string
): Promise<NormalizedCheckoutSession>

Returns: Promise<NormalizedCheckoutSession>

cacheSessionDisplayData

Stash display-only fields (name, totalAmount, currency) for a session ID so the SDK can merge them back into subsequent getCheckoutSession / getUnifiedCheckoutSession calls. (overrideAmount is computed by the backend, so you don't need to stash it.)

Call this on the client immediately after the server returns a session ID, before redirecting to the checkout page. Values are written to sessionStorage (browser) with an in-memory fallback for non-browser environments.

cacheSessionDisplayData(
  sessionId: string,
  data: SessionDisplayCacheData,
  options?: { ttlMs?: number }
): void

import { PaymentAPI } from '@flopay/js';

const paymentAPI = new PaymentAPI(billingApiUrl);

// After your server returns the session ID:
paymentAPI.cacheSessionDisplayData(sessionId, {
  currency: 'EUR',
  products: [
    {
      code: 'initial_charge',
      name: '7 Day Dollar Trial',
      totalAmount: 1,
    },
    {
      code: '4_week_subscription',
      name: 'Hub Membership',
      totalAmount: 24.95,
    },
  ],
});

window.location.href = redirectUrl;

The standalone function cacheSessionDisplayData is also exported from @flopay/js for use without a PaymentAPI instance.

SessionDisplayCacheData

SessionDisplayProduct

Merge rules:

• Products match on code.
• Cache only fills fields the server returned as null / undefined. If the backend starts returning a field again, the server value wins.

clearSessionDisplayData

Drop any cached display data for a session. Call from your success/cancel page after the payment lifecycle completes; otherwise the TTL handles cleanup.

clearSessionDisplayData(sessionId: string): void

import { PaymentAPI } from '@flopay/js';

const paymentAPI = new PaymentAPI(billingApiUrl);
paymentAPI.clearSessionDisplayData(sessionId);

The standalone function clearSessionDisplayData is also exported from @flopay/js. A companion getSessionDisplayData(sessionId) is available for reading the current cache entry (returns null if nothing is cached or the TTL has elapsed).

processPayment

Submit a tokenized payment to the billing backend. The backend will either succeed, return type: '3ds_required', or return type: 'paypal_redirect_required'.

async processPayment(
  userId: string,
  data: ProcessPaymentParams
): Promise<Response>

Returns: Promise<Response> -- the raw fetch response.

Endpoint: POST /v1/checkouts/sessions/{sessionId}/process

createPaymentIntent

Create a PaymentIntent on the backend with the client's payment method attached.

async createPaymentIntent(
  sessionId: string,
  email: string,
  paymentMethodType: string,
  options?: { signal?: AbortSignal; isPaypal?: string }
): Promise<Response>

Returns: Promise<Response>

Endpoint: POST /v1/checkouts/payments/intents

createSetupIntent

Create a SetupIntent for saving payment methods without an immediate charge.

async createSetupIntent(
  sessionId: string,
  email: string,
  paymentMethodType: 'card' | 'google_pay' | 'apple_pay' | 'paypal_express_checkout',
  options?: { signal?: AbortSignal }
): Promise<Response>

Returns: Promise<Response>

Endpoint: POST /v1/checkouts/payments/setup-intents

getPaymentsByEmail

Fetch a user's prior payments by email. Used to determine if saved card UX should be shown.

async getPaymentsByEmail(
  email: string,
  options?: { signal?: AbortSignal; page?: number; limit?: number }
): Promise<{ data: Array<{ id: string }>; total: number; page: number; limit: number }>

Returns: Paginated list of payment records.

Throws: FloPayError with type 'api_error' if the request fails.

Endpoint: GET /v1/payments?email=...&page=...&limit=...&sortField=createdAt&sortDirection=DESC