Accept payments with stored card credentials

Last updated: September 2, 2026

With Vault, you can store your customers' payment card details as Payment instruments, which you can later reuse in future payments so they do not have to input their details every time they make a purchase.

Flow for mobile enables customers to store their card credentials in Vault during checkout. The next time the customer shops with you, we display their stored card details.

For new customers, call the Request a Payment Session endpoint and set the payment_method_configuration.card.store_payment_details field to collect_consent. This value displays the option to store card credentials for future payments. If you have already collected consent from the customer, you can provide payment_method_configuration.card.store_payment_details: "enabled" instead.

You must also provide either the customer.email or customer.id fields.

Information

If your payment session request omits customer.email, the backend silently downgrades store_payment_details: collect_consent to disabled, and the consent checkbox does not display. If your customers are not seeing the consent checkbox, check your session request before troubleshooting your integration.

When store_payment_details is set to collect_consent, the SDK reports the customer's choice as storeForFutureUse on the tokenization result. Forward this value as source.store_for_future_use on your payment request. Sending nothing means the card is not stored, regardless of what the customer chose. For more information, see the onTokenized reference for iOS and Android.

You can provide the stored customer ID for a returning customer using the payment_method_configuration.stored_card.customer_id field when you Request a Payment Session.

Flow for mobile displays the card details stored for the customer to reuse, as well as the card verification value (CVV) if needed for payment.

Alternatively, if you already have payment instruments that are not stored under any customer, you can provide them using the payment_method_configuration.stored_card.instrument_ids field instead.

Some regions or card schemes, such as Mada, require the card verification value (CVV) when performing a stored card payment. Flow for mobile captures and tokenizes the CVV from the customer when such stored card details are selected.

Optionally, you can set the stored card component's CVV capture field to true to always capture CVV from the customer:

Set storedCardConfiguration.captureCardCvv to true, and pass the configuration in the componentOptions map using PaymentMethodName.StoredCard as the key. Flow embeds the stored card component automatically when the payment session carries a stored_card payment method, so the same configuration applies whether you create the Flow component or the stored card component on its own:


1// 1. Configure the Stored Card options to enable CVV capture
2val storedCardConfiguration = StoredCardConfiguration(
3  captureCardCvv = true // Enable CVV capture for saved cards
4)
5
6// 2. Wrap the configuration in a ComponentOption
7val storedCardOptions = ComponentOption(storedCardConfiguration = storedCardConfiguration)
8
9// 3. Create the SDK configuration
10// Pass the options in the componentOptions map using PaymentMethodName.StoredCard as the key
11val configuration = CheckoutComponentConfiguration(
12  context = activity,
13  publicKey = "pk_sbox_...",
14  environment = Environment.SANDBOX,
15  paymentSession = paymentSessionResponse,
16  componentOptions = mapOf(
17    PaymentMethodName.StoredCard to storedCardOptions
18  )
19)
20
21// 4. Initialize CheckoutComponents (factory.create() is a suspend function)
22val factory = CheckoutComponentsFactory(configuration)
23val checkoutComponents = factory.create()
24
25// 5. Create the desired components
26// Flow component: Displays all available payment methods (Cards, Wallets, and Stored Cards)
27val flowComponent = checkoutComponents.create(ComponentName.Flow)
28
29// Stored Card component: Displays only the customer's saved cards
30val storedCardComponent = checkoutComponents.create(PaymentMethodName.StoredCard)


1let sdk = try await CheckoutComponents(configuration: configuration)
2
3let storedCard = try sdk.create(
4  .storedCard(
5    storedCardConfiguration: .init(
6      captureCVV: true
7    ),
8    cardConfiguration: cardConfiguration
9  )
10)
11
12storedCard.render()

You can also set storedCardConfiguration.captureCVV when you add the .storedCard option to a Flow component:


1let flow = try sdk.create(
2  .flow(
3    options: [
4      .card(),
5      .storedCard(storedCardConfiguration: .init(captureCVV: true))
6    ]
7  )
8)

Accept payments with stored card credentials

Store card credentials

Information

Display stored cards

Capture CVV for stored card