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 gateway field to determine the provider, then wraps the session in a NormalizedCheckoutSession.

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

Returns: Promise<NormalizedCheckoutSession>

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/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=occurredAt&sortDirection=DESC