Save directly without charging

Save card details for online reuse from an in-person transaction.

Use SetupIntents to collect card details without charging the card. Saving cards with Stripe Terminal using SetupIntents requires you to:

Create or retrieve a Customer object.
Create a SetupIntent object to track the process.
Collect a payment method after collecting the customer’s consent.
Submit the payment method details to Stripe.

Compliance

You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer’s payment details. For instance, if you save a customer’s payment method for future use, you need their agreement. Getting that agreement up front allows you to save the customer’s payment details, and potentially even charge the customer when they’re not actively using your website or app, placing a MOTO order, or in your store.

Add terms to your checkout flow that state how you plan to save a customer’s payment method details and let the customer opt in. If you plan to charge the customer while they’re offline, then at a minimum, make sure that your terms also cover the following:

The customer’s agreement to your initiating a payment or a series of payments on their behalf for specified transactions.
The anticipated timing and frequency of payments (for instance, whether charges are for scheduled installment or subscription payments, or for unscheduled top-ups).
How the payment amount is determined.
Your cancellation policy, if you’re setting up the payment method for a subscription service.

Make sure you keep a record of your customer’s written agreement to these terms.

Availability

You can use SetupIntents to collect card details on Visa, Mastercard, American Express, Discover, and co-branded eftpos cards. Interac cards, single-branded eftpos cards, and mobile wallets (for example, Apple Pay or Google Pay) aren’t supported.

Note

If you’re integrating with the Terminal iOS or Android SDK, your applications must be on version 2.x of the SDK to use SetupIntents.

Note

The SetupIntents API is compatible with all BBPOS readers, the M2, Tap to Pay on iPhone, and Tap to Pay on Android. It’s not compatible with the Verifone P400. The server-driven-based SetupIntents API is compatible with BBPOS WisePOS E and Stripe Reader S700.

Create or retrieve a customer

To charge a card saved with Stripe, you must attach it to a Customer.

When you include a customer in your SetupIntent before confirming, Stripe automatically attaches the generated card payment method to the provided Customer object.

Include the following code on your server to create a new Customer.

Command Line

curl -X POST https://api.stripe.com/v1/customers \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

Create a SetupIntent

Note

We recommend providing a customer ID while creating a SetupIntent—doing so attaches the card payment method to the Customer upon successful setup. If you don’t provide a customer ID, you must attach the payment method in a separate call.

A SetupIntent is an object that represents your intent to set up a customer’s payment method for future payments. The SetupIntent tracks the steps of this setup process. For Terminal, this includes collecting and recording cardholder consent.

Client-side

With the iOS, Android, and React Native SDKs, you can create a SetupIntent client-side and provide the customer, onBehalfOf (Connect only), and usage parameters.

There is no client-side with a server-driven integration, so you create your SetupIntent server-side.

Server-side

The JavaScript SDK and server-driven integrations require you to create the SetupIntent on your server. For iOS or Android, you can create the SetupIntent on your server if the information required to start a payment isn’t readily available in your app.

Command Line

curl https://api.stripe.com/v1/setup_intents \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "payment_method_types[]"=card_present \
  -d customer={{CUSTOMER_ID}}

The payment_method_types parameter must include card_present.

The SetupIntent contains a client secret, a key that’s unique to the individual SetupIntent. To use the client secret, you must obtain it from the SetupIntent on your server and pass it to the client side.

post '/create_setup_intent' do
  intent = # ... Create or retrieve the SetupIntent
  {id: intent.id, client_secret: intent.client_secret}.to_json
end

For JavaScript, use the client secret as a parameter when calling collectSetupIntentPaymentMethod. For iOS and Android, first use the client secret to call retrieveSetupIntent, and then use the retrieved SetupIntent to call collectSetupIntentPaymentMethod.

For server-driven integrations, the SetupIntent id is all you need to proceed to payment method collection.

Collect a payment method for saving cards

After you create a SetupIntent, the next step is to collect a payment method with the SDK and collect customer consent. If the customer provides the required form of agreement or consent, set the customerConsentCollected Boolean to true.

Note

Collect customer consent verbally or with a checkbox in your application. You must comply with all applicable laws, rules, and regulations in your region.

For SDKs to collect a payment method, you must connect your app to a reader. The connected reader waits for a card after your app calls collectSetupIntentPaymentMethod.

For a server-driven integration, you must call the process_setup_intent endpoint, which handles both collecting and confirming the SetupIntent. If the customer provides consent, set the customer_consent_collected Boolean to true.

Command Line

curl https://api.stripe.com/v1/terminal/readers/{{READER_ID}}/process_setup_intent \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d setup_intent={{SETUP_INTENT_ID}} \
  -d customer_consent_collected=true

This method collects encrypted payment method data using the connected card reader, and associates the encrypted data with the SetupIntent.

For SDKs, you can cancel collecting a payment method by using the Cancelable object returned by the iOS or Android SDK, calling cancelCollectSetupIntent in the React Native SDK, or calling cancelCollectSetupIntentPaymentMethod in the JavaScript SDK.

For a server-driven integration, you can cancel collecting a payment method by calling cancel_action.

Caution

Collecting a payment method happens locally and requires no authorization or updates to the SetupIntent object until the next step.

Submit the payment method details to Stripe

For SDKs, use confirmSetupIntent to complete the setup.

For a server-driven integration, your previous call to process_setup_intent handles the confirm for you so nothing else is required.

A successful setup returns a succeeded value for the SetupIntent’s status property, along with a generated_card, which is a reusable card payment method you can use for online payments.

Note

The setup_intent.payment_method is a card_present PaymentMethod that represents the tokenization of the card in-store and isn’t chargeable online.

The generated_card payment method automatically attaches to the customer you provided during SetupIntent creation. You can retrieve the generated_card payment method by expanding the SetupIntent’s latest_attempt property.

Command Line

curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "expand[]"=latest_attempt

Alternatively, you can also retrieve the attached payment method by fetching the list of payment methods that gets attached to the customer.

Command Line

curl -G https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}
/payment_methods \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d type=card

If you didn’t provide a customer during SetupIntent creation, you can attach the generated_card to a Customer object in a separate call.

Command Line

curl https://api.stripe.com/v1/payment_methods/{{PAYMENT_METHOD_ID}}
/attach \
  -u "sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}}

If the setup isn’t successful, inspect the returned error to determine the cause. For example, failing to collect and notify Stripe of customer consent results in an error.

Your previous call to process_setup_intent handles confirming for you.