Save directly without charging
Collect details of a present card and save them for online use.
Accounts v2 API support
The Terminal SDK doesn’t support customer-configured Accounts. It only supports Customer objects. You can use Terminal with the Accounts v2 API if all of your customer code is on the server side and doesn’t use the SDK.
Use SetupIntents to collect card or mobile wallet details without charging the card. A SetupIntent can’t save a card_present PaymentMethod directly, but in most cases you can create a reusable generated_card type PaymentMethod that represents the same card. From your customer’s perspective, they’re the same payment method.
Warning
All charges made using the generated_card PaymentMethod are card-not-present (CNP) transactions, and features available to card-present transactions (such as liability shifts and pricing)don’t apply to these charges.
You can use SetupIntents to collect card details on Visa, Mastercard, American Express, Discover, and co-branded Interac, eftpos, and girocard cards. SetupIntents don’t support single-branded Interac, eftpos, and girocard cards.
Tap to Pay doesn’t support co-branded Interac cards, which must be inserted into a reader.
Saving cards with Stripe Terminal using SetupIntents requires you to:
- Create or retrieve a Customer or customer-configured Account object.
- Create a SetupIntent object to track the process.
- After you collect the customer’s consent, collect the payment method and submit the details to Stripe.
Note
The server-driven-based SetupIntents API is compatible with the related setting WisePOS E and Stripe Reader the related setting/the related setting.
Create or retrieve a customer
To charge a card saved with Stripe, you must attach it to a Customer or a customer-configured Account.
When you include a customer in your SetupIntent before confirming, Stripe automatically attaches the generated card payment method to the customer object you provide.
Create a SetupIntent
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.
When you create a SetupIntent, provide the customer object ID in the customer or customer_account parameter to automatically attach the payment method to the customer upon successful setup. If you don’t provide the ID on creation, you must attach the payment method to the customer in a separate call.
You must create the SetupIntent on your server and include card_present in the payment_method_types array. Set usage to on_session if you only intend to reuse the payment method when the customer is in your checkout flow.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Collect a payment method for saving
After you create a SetupIntent, you need to collect a payment method and collect customer consent.
Set allow_redisplay to always or limited, indicating the degree to which the payment method can be shown in a customer checkout flow.
Collect customer consent verbally or with a checkbox in your application. You must comply with all applicable laws, rules, and regulations in your region.
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.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
This method collects encrypted payment method data using the connected card reader, and associates the encrypted data with the SetupIntent. The collection happens locally and requires no authorization or updates to the SetupIntent object until the next step.
Cancel collection
Programmatic cancellation
You can cancel collecting a payment method by calling cancel_action.
Submit the payment method details to Stripe
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.
Note
The SetupIntent.payment_method is a card_present PaymentMethod that represents the tokenization of the physically present card. You can’t charge it online. Future payments use the generated card instead. From the customer’s perspective, they’re the same payment method.
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.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Alternatively, you can retrieve the attached payment method by fetching the list of payment methods that gets attached to the customer.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
If you didn’t provide a customer during SetupIntent creation, you can attach the generated_card to the customer in a separate call.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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.
Mobile wallets considerations
You can only use saved mobile wallets for off_session payments that you initiate on behalf of your customer, such as recurring subscription payments. When you save a digital wallet payment method, the generated_card has allow_redisplay=limited, to indicate its specific usage considerations.
When you attempt to charge a mobile wallet, make sure to set off_session to true when confirming the PaymentIntent. If the customer is present in your checkout flow, you need to instead use the appropriate mobile wallet integration to prompt them for their payment method.
Compliance
You’re responsible for your compliance with all applicable laws, regulations, and network rules when saving a customer’s payment details. For example, the European Data Protection Board has issued guidance regarding saving payment details. These requirements generally apply if you want to save your customer’s payment method for future use. This applies in situations such as presenting a customer’s payment method to them in the checkout flow for a future purchase, or charging them when they’re not actively using your website or app, placing a the related setting order, or in your store.
Add terms to your checkout flow that state how you plan to save payment method details and allow customers to opt in. If you plan to charge the customer while they’re not actively checking out, make sure (at a minimum) 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.
When you save a payment method, you can only use it for the specific purpose that you included in your terms. If you want to charge customers when they’re not actively checking out and also save the customer’s payment method to present to them as a saved payment method for future purchases, you must explicitly collect consent from the customer. One way to do so is with a “Save my payment method for future use” checkbox.