Save and manage payment methodsCopy Anchor Link

Give customers a payment-methods page where they can add the ways they pay, see what is on file, replace a method, and remove one, without making a purchase. FloPay decides which methods can be saved, renders them in a secure surface, verifies each one with the provider, and keeps the reusable credential away from your servers.

Who this is forCopy Anchor Link

This guide is for checkout developers and backend teams building a customer account area for saved payment methods of every type: cards, wallets, PayPal, and bank methods. It builds on the card-only flow in Manage saved cards safely, which stays unchanged.

How the pieces fit togetherCopy Anchor Link

Saving a payment method deliberately splits authority three ways:

• Your trusted server resolves the customer, creates setup sessions, lists saved methods, and removes them. Your merchant credentials, the client UUID and API token, stay server-side and are never sent to a browser.
• The browser receives only a setup sessionId and nonce, and renders FloPayPaymentMethodSetup from @flopay/react.
• FloPay decides which methods the customer can save, verifies the chosen method with the provider, and records it as a saved method only once it is verified.

Card data never reaches your application servers or FloPay's application servers: the card is entered in FloPay's hosted, PCI-compliant card form and the reusable credential stays in the vault. Wallets, PayPal, and bank methods are approved in the provider's own surface, such as the device wallet sheet, a PayPal approval, or the provider's mandate form.

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.

Which methods can be savedCopy Anchor Link

FloPay decides which methods a customer can save, per merchant and customer context: from your connected gateways, their current eligibility, and the resolved country and currency, using the same eligibility policy as checkout. The setup session advertises the result, and the add-payment-method surface renders only what the session advertises. Your code never decides it, and there is no list of methods to configure in the SDK.

These are the methods FloPay can advertise on a setup session today:

Not every method offered at checkout is savable:

• One-off redirect methods authorize a single payment and leave nothing the provider can charge again.
• Buy-now-pay-later methods make a fresh credit decision for each purchase, with no reusable mandate.
• Any other method without a reusable setup path is in the same position until FloPay adds one.

FloPay hides methods that cannot be saved instead of showing them disabled, so every method the customer sees on the add-payment-method surface can actually be saved. A merchant with only card gateways sees exactly the card form. FloPay adds methods to setup one at a time as each gains a reusable setup path. Until a method is advertised, nothing in your integration changes, and when it is, it appears without a code change.

What a saved method can be charged forCopy Anchor Link

A setup session never charges anything. What FloPay can do with the method afterwards depends on its type:

A saved Apple Pay or Google Pay wallet joins the customer's cards: FloPay charges the most recently used method first and falls back to the others, and a subscription can renew on it.

1. Record consent and disclosureCopy Anchor Link

Before starting setup, tell the customer what saving the method means and obtain their affirmative consent for future off-session charges under your terms. Retain the consent text and version, the customer identity, the timestamp, and your business purpose. The setup session and the provider's verification outcome are technical evidence; they do not replace your consent record.

FloPay's hosted card form always shows the card-storage disclosure below its submit button, with a link to the Card Storage Policy, and it cannot be removed or replaced. That disclosure does not replace yours: you keep the responsibility for your own card-storage disclosure, for the mandate and consent terms of any method you let customers save, and for collecting and retaining the customer's agreement to future off-session charges.

2. Resolve the customerCopy Anchor Link

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 customer UUID supplied directly by a browser.

3. Create a setup sessionCopy Anchor Link

Create the no-charge setup session from the same trusted server. It is the same endpoint card setup uses, extended additively: existing card-only integrations keep working unchanged.

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/payment-methods",
  "cancelUrl": "https://merchant.example/account/payment-methods",
  "country": "GB",
  "currency": "GBP",
  "futureUse": "off_session"
}

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

The remaining fields are optional, independent, and nullable:

Send the values you already hold: FloPay owns normalization, validation, and defaults, and may fill an omitted country or currency from this customer's own history with you. FloPay uses country and currency as context when deciding which methods to advertise, but the context never selects or hints a gateway: there is no field, header, or SDK setting that chooses one. See Gateway selection.

@flopay/shared publishes the body as the type-only CreateCardSetupSessionRequest, so you can type the call you make from your server. @flopay/node has no setup method by design, because it would need the merchant credential this call requires:

import type { CreateCardSetupSessionRequest } from '@flopay/shared';

const authorization = `Basic ${Buffer.from(
  `${process.env.FLOPAY_CLIENT_UUID}:${process.env.FLOPAY_API_TOKEN}`,
).toString('base64')}`;

export async function createSetupSession(floPayCustomerUuid: string) {
  const body: CreateCardSetupSessionRequest = {
    userId: floPayCustomerUuid,
    successUrl: 'https://merchant.example/account/payment-methods',
    cancelUrl: 'https://merchant.example/account/payment-methods',
    country: 'GB',
    currency: 'GBP',
  };

  const response = await fetch('https://api.flopay.com/v1/checkouts/sessions/setup', {
    method: 'POST',
    headers: { Authorization: authorization, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw new Error(`Setup session request failed with status ${response.status}`);
  }

  const { data } = await response.json();
  // Return only the opaque session id and nonce to the browser.
  return { sessionId: data.uuid as string, nonce: data.nonce as string };
}

201 Created returns the checkout-session shape with checkoutMode: 'setup', no products, and no amount, together with the methods this session can save (advertisedPaymentMethods) and its currency. The component reads both for you, so your server only needs to hand over the session id and nonce. Do not forward the merchant Authorization header, and do not call the purchase process endpoint for a setup session.

4. Render the add-payment-method surfaceCopy Anchor Link

Mount FloPayPaymentMethodSetup with the session id and nonce. It renders every method the setup session advertises and saves the customer's choice without a purchase. A card-only session behaves exactly like FloPayCardSetup.

'use client';

import { FloPayPaymentMethodSetup } from '@flopay/react/payment-method-setup';
import { useState } from 'react';

type AddPaymentMethodProps = {
  sessionId: string;
  nonce: string;
  onSaved: (savedCardId: string | undefined) => void;
  onLeft: () => void;
};

export function AddPaymentMethod({ sessionId, nonce, onSaved, onLeft }: AddPaymentMethodProps) {
  const [message, setMessage] = useState<string | null>(null);

  return (
    <>
      <FloPayPaymentMethodSetup
        sessionId={sessionId}
        nonce={nonce}
        onComplete={(event) => {
          setMessage(null);
          // Present for a card. List the methods again from your server for every type.
          onSaved(event.paymentMethod?.id);
        }}
        onDecline={(event) => {
          setMessage(event.message ?? 'That payment method could not be verified. Try another one.');
        }}
        onCancel={() => onLeft()}
        onError={(error) => {
          // Keep the form mounted on a retryable error: the customer can try again.
          setMessage(error.retryable ? 'Something went wrong. Please try again.' : error.message);
        }}
      />
      {message ? <p role="alert">{message}</p> : null}
    </>
  );
}

Import from @flopay/react/payment-method-setup on a page that only saves methods: it loads a provider's script only when the session advertises one of that provider's methods. The component is also exported from @flopay/react.

The component is browser-only, needs nothing but sessionId and nonce, and does not need FloPayProvider. It also accepts theme, containerStyle, loading, billingApiUrl, telemetry, onReady, and onValidation, as listed in the FloPayPaymentMethodSetup reference.

What the customer seesCopy Anchor Link

The form is laid out the way FloPayCheckout lays out a purchase, using the same components, so customers meet one familiar surface:

1. Wallet buttons, such as Apple Pay and Google Pay.
2. PayPal.
3. One tile for each bank method. Pressing a tile opens that method's form with a Save button.
4. An or add a card rule.
5. FloPay's hosted card form.

A method the provider cannot offer in this browser is left out without an error: a wallet the device does not have, or a method that does not support the session currency. That is why two customers on the same session settings can see different wallets. Do not render your own list of offered methods beside the form: it can name a method the form has correctly left out.

5. Handle the setup outcomesCopy Anchor Link

Each callback reports one outcome. Treat only completion as success:

Do not treat mount, submit, or a provider redirect as success. A declined, abandoned, redirect-incomplete, or authentication-incomplete setup never creates an active method and never changes an existing one.

Completion is FloPay's decision. After the customer approves a wallet, PayPal, or a bank method, the form shows SAVING PAYMENT METHOD... and reads the setup session until FloPay reports it completed, then fires onComplete. Some bank methods are verified by the provider later: the method stays pending until then and becomes active without any further call from you. A customer who leaves during that wait triggers onCancel, so always treat the list from your server as the source of truth.

The error codes you are most likely to handle:

The complete list is in the FloPayPaymentMethodSetup reference.

Returning from a provider redirectCopy Anchor Link

Some methods send the customer to the provider and back to the page they left. To finish that setup, mount FloPayPaymentMethodSetup again with the same sessionId and nonce when the customer returns. It reads the provider's return parameters from the URL, removes them, and reports the outcome through the same callbacks.

Keep the open setup's sessionId and nonce somewhere that survives the navigation, such as the tab's session storage, and clear them once a callback reports an outcome.

6. List saved methods with the type filterCopy Anchor Link

List the customer's saved methods from your trusted server. Add status[eq]=active for methods the customer can use, and type[eq]= to show one type at a time:

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

type takes the method type: card, paypal, apple_pay, google_pay, sepa_debit, or us_bank_account. type[in]=card,apple_pay returns several types at once, and any other value returns 400. Leave type out to list every saved method together.

Every row has the same envelope, and two display fields tell you what to show:

Card fields are null on every row that is not a card. Read methodType defensively and show a row's displayLabel for a type your interface does not recognize yet, instead of hiding the row. The full response is in the payment methods REST reference.

The API never returns provider secrets, client secrets, vault or provider tokens, provider payment-method ids, or full account details such as a card number, CVC, or bank account number. Keep each method's FloPay id on your server for later removal. Customers may hold several active methods, including several of the same type.

7. Replace a methodCopy Anchor Link

There is no replace endpoint. Replace is a composition of the operations above:

1. Complete setup for the new method.
2. Confirm that the exact new method is active in the list.
3. Call DELETE /v1/payment-methods/{id} for the old method.

onComplete carries a new card's id in event.paymentMethod. For any other method it does not, so do not guess the new method from the newest row: a setup on another device can make that pick the wrong method. Leave the old method in place and let the customer remove it from the list themselves.

If setup fails, leave the old method unchanged. When the old method funds a subscription, FloPay moves that funding only to an eligible active method of the same type, verifies the move, and only then removes the old method, so a card is never replaced by a wallet or the reverse. If deletion returns a conflict or a gateway error, keep the old method visible and explain the next step; never hide it optimistically.

8. Remove a methodCopy Anchor Link

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

A 409 leaves the method exactly as it was. Removed methods remain as sanitized tombstones with status deleted, so filter on status[eq]=active for your list. Payment, refund, and audit history stay intact.

Security checklistCopy Anchor Link

• Create setup sessions, list methods, and remove methods only on your trusted server. Merchant credentials stay server-side.
• Hand the browser only sessionId and nonce.
• Treat only onComplete, confirmed by an active row in the list, as a saved method.
• Show only display fields. Never log or return raw card or bank data.
• Treat every 404 alike and do not probe whether another merchant owns an id.
• Keep your disclosure and the customer's consent for future off-session charges.

See the FloPayPaymentMethodSetup reference for the component's props, events, and errors, and the payment methods REST reference for the complete request, response, and error contract.