Collect card payments while offlineBeta
Collect card payments with intermittent, limited, or no internet connectivity.
The Terminal SDK allows your application to continue collecting payments using a smart reader without an Internet connection.
If you’re using a separate POS device with a Stripe smart reader, you still need a functioning local network to allow your POS device to communicate with the smart reader. Operating offline with smart readers is for scenarios where your POS and reader can’t communicate with Stripe, such as during an ISP outage. If you need to operate offline without a local network, consider Stripe Terminal’s mobile readers.
You can also operate offline with an Apps on Devices integration. Since your POS application runs directly on the smart reader, you don’t need a local network to collect payments. However, you still need to be on a local network when your reader first boots up, even if the network doesn’t have access to the Internet.
Warning
When operating offline, payment information is collected at the time of sale, and authorization is only attempted after connectivity is restored and the payment is forwarded. You, as the user, assume all decline risk of the transaction. If the issuer declines the offline transaction, there’s no way to recover the funds, and you might not receive payment from the customer for goods or services already provided.
To reduce the chances of an issuer decline, you’re encouraged to:
- Reestablish internet connectivity as soon as possible to record the payments to Stripe.
- Restrict transactions if they exceed a certain amount.
- Fail all offline payments if the SDK has stored a set of transactions whose sum exceeds a certain amount.
Collect payments while offline
Offline payments follow the same steps as online payments: create, collect, process, and capture the payment. Your device can transition from online to offline at any step in the process.
- Enable offline mode
- Connect to a reader while offline
- Handle offline events
- Create a PaymentIntent while offline
- Collect a payment method
- Confirm the payment
- Wait for payments to forward
- Capture the payment
- Examine offline payments
Enable offline mode
Note
The offline mode feature is in private beta. To request access, please email stripe-terminal-betas@stripe.com. After we enable the changes for your account and you’ve enabled the feature using the Configuration API, you must disconnect and reconnect to your reader using the SDK for the updated configuration to take effect.
To use offline mode, your application needs to consume version 3.
or later of the Terminal Android SDK.
Use a Configuration object to enable offline mode for the Stripe Reader S700, BBPOS WisePOS E. devices at your Location
.
After you enable offline mode on a Configuration
object, you can assign it to a Location
. You can also enable offline mode by default for all Locations
by updating the default Configuration
object for your account. Configuration API changes can take several minutes to propagate to your SDK and reader, and require you to disconnect from and reconnect to your reader to take effect.
Connect to a reader while offline
To collect payments with a smart reader while offline, you must have previously connected to that reader at the same Location
while online, on the same local network, within the last 30 days. The reader stores the Location
information locally after connecting online, and it derives configuration information from that Location
while operating offline.
Your reader and POS device must be on the same local network used to connect online. You can’t switch networks while offline.
Handle offline eventsClient-side
Implement the OfflineListener
interface and pass it to Terminal to notify your application of offline-related events. You must set OfflineListener
before collecting payments offline.
Create a PaymentIntent while offlineClient-side
To support operating offline, you must use the SDK’s createPaymentIntent
to create PaymentIntent objects.
While operating offline, PaymentIntent
objects have a null id
. We recommend adding a custom identifier to the PaymentIntent’s metadata to help reconcile PaymentIntent
objects created offline.
You can set up a webhook endpoint to receive PaymentIntent
events when offline payments are forwarded to Stripe, and use your identifier to associate them with a PaymentIntent
ID.
Managing risk while offline
The Terminal.
accepts a CreateConfiguration
parameter. By default, if you’re operating offline, the Terminal reader stores all offline payments, then forwards them to Stripe’s backend when connectivity is restored. You can pass a CreateConfiguration
object with offlineBehavior
set to REQUIRE_
to fail the current transaction if you’re operating offline. You might want to disallow transactions above a certain amount or disallow all offline transactions if the reader has stored a set of transactions whose sum exceeds a certain amount.
The SDK exposes two properties to help you manage risk:
Terminal.
offlineStatus. reader. offlinePaymentsCount Terminal.
offlineStatus. reader. offlinePaymentAmountsByCurrency
Managing latency while offline
By default, the Terminal SDK automatically determines whether to collect payments online or offline based on your network connectivity. However, you might want to operate offline despite having an active network connection – for example, if you need to collect transactions quickly and your network connection is slow. You can pass a CreateConfiguration
object with offlineBehavior
set to FORCE_
to collect the payment offline regardless of connectivity. Payments collected offline while the Terminal reader has an active network connection are forwarded in the background.
Collect a payment methodClient-side
Swiping cards isn’t supported while offline. Tapping cards is also not supported in markets where Strong Customer Authentication is required.
Your smart reader automatically displays the available payment options to the customer.
Using the updatePaymentIntent
parameter in CollectConfiguration
is disabled when offline mode is enabled unless offlineBehavior
is set to REQUIRE_
.
Note
Payment liability is your responsibility when operating your reader offline. Because magnetic stripe data is easy to spoof, Stripe disallows this option while operating offline.
Confirm paymentClient-side
This step is similar to confirming payments while online. The primary difference is that your integration must handle offline-specific error cases, such as when the transaction exceeds the Stripe-enforced offline maximum of 10,000 USD or equivalent in your operating currency.
In some cases, the SDK might create a PaymentIntent
online, but confirm it while offline. When this happens, the PaymentIntent
might have a non-null id
. You can check if offlineDetails
is defined to determine if it was confirmed offline.
Providing receipts
You might require information about the card used to complete a payment while offline. For example, you might need to generate a receipt for customers who require one at the time of purchase.
If the PaymentIntent is confirmed offline, retrieve its OfflineCardPresentDetails from the paymentIntent.
property.
This hash contains a ReceiptDetails property you can use to generate a receipt, as well as other card details like the cardholder name and card brand.
Not all receipt details are available while operating offline. Prebuilt email receipts are only sent after connectivity is restored and the payment is successfully captured.
Wait for payments to forwardClient-side
When network connectivity is restored, the reader automatically begins forwarding the stored offline payments.
If you disconnect or power off your smart reader too soon, your payments might not be forwarded. You can query Terminal.
to make sure your reader is online and can forward payments, and Terminal.
to check how many payments the reader has to be forwarded.
If your smart reader becomes damaged or otherwise can’t take payments, your stored payments can often still be forwarded. Make sure to connect the smart reader to your POS and re-establish Internet access to allow it to re-connect to Stripe.
Capture payment
Note
While offline, you can create PaymentIntents with captureMethod
set to automatic
. Once you confirm these PaymentIntents, they have a SUCCEEDED
status instead of REQUIRES_
. Stripe automatically captures the payments after you forward them.
Payments that are successfully forwarded and authorized require capture from your backend or application:
- To capture payments from your backend, use webhooks to listen for PaymentIntents with a
requires_
status.capture - To capture payments from your application, wait for your application to receive calls to
OfflineListener::onPaymentIntentForwarded
for each PaymentIntent as the reader forwards it. A PaymentIntent is ready to capture if its status isREQUIRES_
.CAPTURE
If your application determines when to capture a PaymentIntent after confirmPaymentIntent
, they’re ready to capture when the status is REQUIRES_
, and the offlineDetails
is null or has a requiresUpload
value of false
.
Capture a payment after confirmPaymentIntent
, if it’s confirmed online:
Capture an offline payment after the reader forwards it in your OfflineListener::onPaymentIntentForwarded
:
Examine payments collected offline
After authorization, you can use the PaymentIntents API to examine offline details on a payment. Access the payment method details on the latest Charge object on a PaymentIntent
to determine if it was collected offline.