Manage Saved Cards

Customers can now save a card without making a purchase, see the cards they have on file, and replace or remove them whenever they like. The whole journey runs on FloPay's hosted card form, so full card numbers, CVCs, and reusable payment credentials never enter your pages — and your merchant credentials never leave your server. Requires v1.5 or later of the SDK.

Add a card without a purchase

Create a no-charge setup session from trusted server code with POST /v1/checkouts/sessions/setup, then hand only the opaque sessionId and nonce to the browser. The FloPayCardSetup component from @flopay/react mounts the hosted card form and reports success only after provider verification, including any required 3DS step — a declined or abandoned setup never produces an active card.

Recognise cards safely

List a customer's active cards from your server with GET /v1/payment-methods?userUuid={id}&status[eq]=active and display the safe details it returns: brand, last four digits, and expiry. Provider and vault identifiers stay out of the browser entirely.

Replace and remove with guardrails

Replacing a card is a safe composition: verify the new card through setup, then call DELETE /v1/payment-methods/{paymentMethodId} for the old one. FloPay reassigns eligible subscription funding to the verified replacement and confirms the reassignment before deleting anything. Removal is idempotent, and explicit conflict responses — such as payment_method_in_use or payment_method_has_active_payment — tell you exactly what to show the customer when a card cannot be removed yet.

What's included

• Checkout API — Setup sessions for saving a card without a charge, active payment-method listing, and idempotent deletion with an explicit conflict contract.
• SDK — The FloPayCardSetup component with verified-only completion and dedicated decline, error, and cancel callbacks.
• Demo — A saved-cards page showing the full journey: recognise, add, replace, and remove.

Developer notes

Keep customer resolution, setup-session creation, listing, and deletion on your trusted server; never forward your merchant Authorization header to the browser. Treat a setup as complete only when the verified payment-method id is present, and use that exact id for replacement. Obtain and retain customer consent before saving a card for future off-session charges. The full flow is covered in the saved-card management guide.

Why it matters

Returning customers check out faster with a card they already trust, and card management stops being a support task. You get the convenience features of card-on-file with a PCI-lean integration: sensitive data stays inside FloPay's hosted form, and every destructive action is verified before anything is deleted.