Saved-card management

Saved-card management deliberately splits authority:

• your trusted server resolves the customer, creates setup sessions, lists cards, and removes cards using merchant credentials;
• the browser receives only a setup sessionId and nonce, then uses FloPay's hosted card form;
• neither FloPay's SDK nor your browser receives a user-owned API token, a reusable provider credential, a PAN, or a CVC.

Client Basic authentication uses the client UUID as the username and an active user-owned API token as the password. In the examples below, {base64(clientUuid:apiToken)} represents that encoded pair.

1. Record consent

Before starting setup, show the customer what saving the card means and obtain affirmative consent for future off-session charges under your terms. Retain the consent text/version, customer identity, timestamp, and your business purpose. The authenticated FloPay setup session and provider authentication outcome are technical evidence, but they do not replace your consent record.

2. Resolve your customer id

The setup and list APIs use FloPay's customer UUID. If you store your own customer id, resolve it from your trusted server:

GET /v1/users?clientUserId=customer_123
Authorization: Basic {base64(clientUuid:apiToken)}

Read the first exact match's id from the paginated data array. An empty array means there is no customer linked to this merchant. Never accept a FloPay user UUID supplied directly by an untrusted browser.

3. Create a setup session

Create the no-charge session from the same trusted server:

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"
}

userId is the resolved FloPay UUID. The customer must be linked to the authenticated merchant. Unknown and cross-merchant customers both return 404 Not Found before FloPay contacts a provider.

Return only the response's opaque sessionId and nonce to the browser. Do not forward the merchant Authorization header.

4. Mount the hosted setup form

Mount the setup-specific component from @flopay/react. It rejects purchase sessions and never displays payment-success wording:

import { FloPayCardSetup } from '@flopay/react';

export function AddCard({ sessionId, nonce }) {
  return (
    <FloPayCardSetup
      sessionId={sessionId}
      nonce={nonce}
      onComplete={(card) => {
        notifyYourServerThatSetupCompleted({
          sessionId,
          paymentMethodId: card.paymentMethodId,
        });
      }}
      onDecline={(decline) => showCardSetupDecline(decline)}
      onCancel={() => showCardSetupCancelled()}
    />
  );
}

The component mounts FloPay's hosted vault form and reports success only after provider verification, including any required 3DS step. A declined, abandoned, or authentication-incomplete setup never produces an active card and never changes an existing usable card.

Do not treat mount, submit, or action_required as success. A safe replace flow requires the exact payment-method id produced by the verified setup. If the released terminal result does not include that id, stop the replacement and reconcile it through support; never select “the newest row” because concurrent setup on another device can make that heuristic delete the wrong card.

5. Recognise saved cards safely

List only the customer's active methods from your trusted server:

GET /v1/payment-methods?userUuid=3b4d9a11-0ce8-4a88-9cb1-b4f43d03d2b7&status[eq]=active
Authorization: Basic {base64(clientUuid:apiToken)}

Display brand, lastFour, expiryMonth, and expiryYear. Keep the FloPay method id on your server for later removal; do not expose provider or vault identifiers. Customers may hold multiple active cards.

<li key={card.id}>
  {card.brand} ending {card.lastFour} — expires {card.expiryMonth}/{card.expiryYear}
</li>

6. Replace a card

Replace is composition, not a separate endpoint: complete setup for the new card, confirm that exact method is active, then call DELETE /v1/payment-methods/{oldMethodId} for the old card. FloPay reassigns eligible Stripe subscription/customer funding to the most recently charged or setup-verified replacement and verifies the reassignment before deleting the old method.

If setup fails, leave the old card unchanged. If deletion returns a conflict or gateway error, also leave the old card visible and explain the next action; never hide it optimistically.

7. Remove a card

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

The API deletes provider/vault artifacts through durable checkpoints and retains only a sanitised tombstone. Payment, refund, and approved audit history remain intact.

Security checklist

• Run user resolution, setup-session creation, listing, and deletion only on your trusted server.
• Show only brand, last four, and expiry. Never log or return raw card data.
• Treat every 404 alike and do not probe whether another merchant owns an id.
• Wait for a verified active method before replacing or removing the old one.
• Keep consent evidence for future off-session use.

See the payment methods REST reference for the complete response and error contract.