Payment methods

All operations are merchant-authenticated and client-scoped. Client Basic authentication uses the client identifier (client.uuid) as the username and an active user-owned API token as the password; OAuth callers use a bearer token with the required scope. Credentials must remain on a trusted server.

Create a card-setup session

POST /v1/checkouts/sessions/setup
Authorization: Basic {base64(clientUuid:apiToken)}
Content-Type: application/json

{
  "userId": "3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7",
  "successUrl": "https://merchant.example/account/cards/added",
  "cancelUrl": "https://merchant.example/account/cards"
}

The setup request's userId and the list endpoint's userUuid query parameter both identify the same FloPay customer UUID. Keep the endpoint-specific key names shown here when making each request.

201 Created returns the existing checkout-session shape with checkoutMode: 'setup', no products, no amount, and an embedded vault block. Give the browser only the session id and nonce; the setup-specific SDK component reads the session through that scoped handoff. Do not call the purchase process endpoint for a setup session.

FloPay verifies the card with a Stripe SetupIntent configured for later off-session use. The saved method remains pending until verification succeeds. A declined, abandoned, processing, or authentication-incomplete setup does not create an active method. Successful verification changes it to active and makes it the most recently usable card.

Unknown and cross-merchant users both return 404 before provider or vault work. Card setup is Stripe-only; it does not charge the card and does not create purchase or fulfilment events.

List payment methods

GET /v1/payment-methods?userUuid={floPayUserUuid}&status[eq]=active
Authorization: Basic {base64(clientUuid:apiToken)}

Filters include uuid, userUuid, type, provider, status, createdAt, and updatedAt, with the standard pagination and sorting parameters.

{
  "data": [
    {
      "id": "452d914f-078d-4a68-a9ef-16cac0dd2ed4",
      "type": "card",
      "brand": "visa",
      "lastFour": "4242",
      "expiryMonth": 12,
      "expiryYear": 2030,
      "payerEmail": null,
      "status": "active",
      "createdAt": "2026-08-06T10:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

The display DTO contains only id, type, brand, lastFour, expiryMonth, expiryYear, payerEmail, status, non-secret gateway data when loaded, and createdAt.

The API never returns a PAN. It never returns a CVC. It never returns a vault token, provider payment-method id, client secret, billing-address snapshot, or reusable capture credential.

Customers may retain multiple active cards. Use the returned FloPay id for server-side removal and the display fields for recognition.

Delete a payment method

DELETE /v1/payment-methods/{id}
Authorization: Basic {base64(clientUuid:apiToken)}

The payment method is accessible only when its owning gateway belongs to the authenticated client and its user is linked to that client.

For a 502, retrySafe: true means repeating the same DELETE is idempotent; it does not promise that retrying alone will fix provider configuration or verification. Keep the method visible until a later list confirms its terminal state.

Stripe replacement candidates must be active and belong to the same user, gateway, provider, type, and Stripe Customer. FloPay chooses the most recently successfully charged or setup-verified candidate, reassigns subscription/customer funding, verifies it, and only then removes the target. A failure preserves the old method.

See Saved-card management for consent, browser handoff, recognition, and safe replacement sequencing.