Save directly without charging

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 Customer object you provide.

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

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

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.

You must create the SetupIntent on your server and include card_present on the payment_method_types parameter.

The SetupIntent contains a client secret, which is a key that’s unique to the individual SetupIntent. You must obtain the client secret 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

After you create a SetupIntent, you need to collect a payment method and collect customer consent. Pass allow_redisplay as always or limited, indicating the degree to which a payment method can be shown in a customer checkout flow.

You must call the process_setup_intent endpoint, which handles both collecting and confirming the SetupIntent. If the customer provides consent, set allow_redisplay to either always or limited.

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

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

Cancel collection

Programmatic cancellation

You can cancel collecting a payment method by calling cancel_action.

Your previous call to process_setup_intent handles the confirm for you, so no further action is necessary.

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

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. Always check for a generated_card value, because for payment methods that don’t allow generated cards, the value is empty.

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

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

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.

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.

If your MCC is in one of the following ranges, you might be eligible to participate in a limited beta for saving digital wallet payment methods. For more details, contact stripe-terminal-betas@stripe.com.

• Car Rental Agencies (3351 - 3500)
• Lodging – Hotels, Motels, Resorts (3501 - 3999)
• Steamship and Cruise Lines (4411)
• Boat Rentals and Leasing (4457)
• Lodging - Hotels, Motels, Resorts, Central Reservations Services (Not Elsewhere Classified) (7011)
• Trailer Parks and Campgrounds (7033)
• Equipment, Tool, Furniture, and Appliance Rental and Leasing (7394)
• Car Rental Agencies (Not Elsewhere Classified) (7512)
• Truck and Utility Trailer Rentals (7513)
• Motor Home and Recreational Vehicle Rentals (7519)

When you save a digital wallet payment method, the generated_card has allow_redisplay=limited, because checkout flows are prohibited from presenting saved digital wallets as a payment option. You can only charge saved digital wallet payment methods for off_session payments.