Collect card payments
Prepare your application and backend to collect card payments using Stripe Terminal.
Note
For smart readers, such as the BBPOS WisePOS E reader or Stripe Reader S700, we recommend using the server-driven integration instead of the JavaScript SDK. The server-driven integration uses the Stripe API instead of relying on local network communications to collect payments. See our platform comparison to help you choose the best platform for your needs.
Collecting payments with Stripe Terminal requires writing a payment flow in your application. Use the Stripe Terminal SDK to create and update a PaymentIntent, an object representing a single payment session.
Designed to be robust to failures, the Terminal integration splits the payment process into several steps, each of which can be retried safely:
- Create a PaymentIntent.
- Collect a payment method. You can define whether to automatically or manually capture your payments.
- Process the payment. Authorization on the customer’s card takes place when the SDK processes the payment.
- (Optional) Capture the payment
Note
This integration shape does not support offline card payments.
Create a PaymentIntentServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The first step when collecting payments is to start the payment flow. When a customer begins checking out, your application must create a PaymentIntent
object. This represents a new payment session on Stripe.
Use test amounts to try producing different results. An amount ending in 00
results in an approved payment.
The following example shows how to create a PaymentIntent
on your server:
For Terminal payments, the payment_
parameter must include card_
.
You can control the payment flow as follows:
- To fully control the payment flow for
card_
payments, set thepresent capture_
tomethod manual
. This allows you to add a reconciliation step before finalizing the payment. - To authorize and capture payments in one step, set the
capture_
tomethod automatic
.
To accept Interac payments in Canada, you must also include interac_
in payment_
. For more details, visit our Canada documentation.
The PaymentIntent
contains a client secret, a key that’s unique to the individual PaymentIntent
. To use the client secret, you must obtain it from the PaymentIntent
on your server and pass it to the client side.
Use the client secret as a parameter when calling collectPaymentMethod.
The client_
is all you need in your client-side application to proceed to payment method collection.
Collect a payment method Client-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After you’ve created a PaymentIntent
, the next step is to collect a payment method with the SDK.
In order to collect a payment method, your app needs to be connected to a reader. The connected reader waits for a card to be presented after your app calls collectPaymentMethod
.
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret); if (result.error) { // Placeholder for handling result.error } else { // Placeholder for processing result.paymentIntent } }
This method collects encrypted payment method data using the connected card reader, and associates the encrypted data with the local PaymentIntent
.
Note
Collecting a payment method happens locally and requires no authorization or updates to the Payment Intents API object until the next step, process the payment.
Optionally inspect payment method details Beta![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
For advanced use cases, you can examine the payment method details of the presented card and perform your own business logic prior to authorization.
Use the update_
parameter to attach a PaymentMethod
to the server-side PaymentIntent
. This data is returned in the collectPaymentMethod
response.
async () => { // clientSecret is the client_secret from the PaymentIntent you created in Step 1. const result = await terminal.collectPaymentMethod(clientSecret, { config_override: { update_payment_intent: true } }); if (result.error) { // Placeholder for handling result.error } else { const pm = result.paymentIntent.payment_method const card = pm?.card_present ?? pm?.interac_present // Placeholder for business logic on card before processing result.paymentIntent } }
Note
This method attaches the collected encrypted payment method data with an update to the PaymentIntent
object. It requires no authorization until the next step, process the payment.
This advanced use case isn’t supported on the Verifone P400 or with simulated Terminal readers.
You can access attributes like card brand, funding, and other useful data at this point.
Note
Stripe attempts to detect whether a mobile wallet is used in a transaction as shown in the wallet.
attribute. However, the attribute isn’t populated if the card’s issuing bank doesn’t support reader-driven identification of a mobile wallet, so accurate detection isn’t guaranteed. After authorization in the confirmation step, Stripe receives up-to-date information from the networks and updates wallet.
reliably
Cancel collection ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Programmatic cancellation![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can cancel collecting a payment method by calling cancelCollectPaymentMethod in the JavaScript SDK.
Customer-initiated cancellation![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
When you set enable_
to true for a transaction, smart reader users see a cancel button.
Tapping the cancel button cancels the active transaction.
terminal.collectPaymentMethod( clientSecret, { config_override: { enable_customer_cancellation: true } } )
Handle events ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Note
The JavaScript SDK only supports the Verifone P400, BBPOS WisePOS E, and Stripe Reader S700, which have a built-in display. Your application doesn’t need to display events from the payment method collection process to users, because the reader displays them. To clear the payment method on a transaction, the cashier can press the red X key.
Confirm the paymentClient-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After successfully collecting a payment method from the customer, the next step is to process the payment with the SDK. When you’re ready to proceed with the payment, call processPayment
with the updated PaymentIntent
from Step 2.
- For manual capture of payments, a successful
processPayment
call results in aPaymentIntent
with a status ofrequires_
.capture - For automatic capture of payments, the
PaymentIntent
transitions to asucceeded
state.
async () => { const result = await terminal.processPayment(paymentIntent); if (result.error) { // Placeholder for handling result.error } else if (result.paymentIntent) { // Placeholder for notifying your backend to capture result.paymentIntent.id } }
Warning
You must manually capture a PaymentIntent within 2 days or the authorization expires and funds are released to the customer.
Handle failures ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
When processing a payment fails, the SDK returns an error that includes the updated PaymentIntent
. Your application needs to inspect the PaymentIntent
to decide how to deal with the error.
PaymentIntent Status | Meaning | Resolution |
---|---|---|
requires_ | Payment method declined | Try collecting a different payment method by calling collectPaymentMethod again with the same PaymentIntent . |
requires_ | Temporary connectivity problem | Call processPayment again with the same PaymentIntent to retry the request. |
PaymentIntent is nil | Request to Stripe timed out, unknown PaymentIntent status | Retry processing the original PaymentIntent . Don’t create a new one, because that could result in multiple authorizations for the cardholder. |
If you encounter multiple, consecutive timeouts, there might be a problem with your connectivity. Make sure that your app can communicate with the internet.
Avoiding double charges ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The PaymentIntent
object enables money movement at Stripe—use a single PaymentIntent
to represent a transaction.
Re-use the same PaymentIntent
after a card is declined (for example, if it has insufficient funds), so your customer can try again with a different card.
If you edit the PaymentIntent
, you must call collectPaymentMethod
to update the payment information on the reader.
A PaymentIntent
must be in the requires_
state before Stripe can process it. An authorized, captured, or canceled PaymentIntent
can’t be processed by a reader.
Capture the paymentServer-side![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
If you defined capture_
as manual
during PaymentIntent
creation in Step 1, the SDK returns an authorized but not captured PaymentIntent
to your application. Learn more about the difference between authorization and capture.
When your app receives a confirmed PaymentIntent
from the SDK, make sure it notifies your backend to capture the payment. Create an endpoint on your backend that accepts a PaymentIntent
ID and sends a request to the Stripe API to capture it:
A successful capture
call results in a PaymentIntent
with a status of succeeded
.
Note
To make sure the application fee captured is correct for connected accounts, inspect each PaymentIntent
and modify the application fee, if needed, before manually capturing the payment.
Reconcile payments ![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To monitor the payments activity of your business, you might want to reconcile PaymentIntents with your internal orders system on your server at the end of a day’s activity.
A PaymentIntent
that retains a requires_
status might represent two things:
Unnecessary authorization on your customer’s card statement
- Cause: User abandons your app’s checkout flow in the middle of a transaction
- Solution: If the uncaptured
PaymentIntent
isn’t associated with a completed order on your server, you can cancel it. You can’t use a canceledPaymentIntent
to perform charges.
Incomplete collection of funds from a customer
- Cause: Failure of the request from your app notifying your backend to capture the payment
- Solution: If the uncaptured
PaymentIntent
is associated with a completed order on your server, and no other payment has been taken for the order (for example, a cash payment), you can capture it.
Collect tips US only![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
In the US, eligible users can collect tips when capturing payments.