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 mobile reader without a network connection.
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
To use offline mode, your application needs to consume version 3.
or later of the Terminal iOS SDK.
Use a Configuration object to enable offline mode for the BBPOS Chipper 2X BT, Stripe Reader M2 or BBPOS WisePad 3 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
The SDK stores necessary Location
information locally after connecting online. On subsequent offline connections, it uses the stored configuration information from that Location
.
To connect to a reader while offline, you must have previously connected to any mobile reader of the same type at the same Location
while online within the last 30 days, and have updated your reader’s software within that time. If you attempt to connect to a reader while offline without meeting these requirements, the request fails with an error.
Error | Resolution |
---|---|
The SDK isn’t connected to the internet | Make sure the Location you’re using is configured for offline mode. Otherwise, if your Location is properly configured, your POS hasn’t previously connected to any readers while online. You should first connect to any reader while online, and then connect to a reader of the same type while offline. |
The selected reader requires a software update before it can be used to collect payments offline. | The reader’s software hasn’t been updated in 30 days or more. Connect to the reader while online to update it. |
The selected reader must be paired online at this location before it can be used to collect payments offline. | You’re attempting to connect to a reader type that your POS hasn’t previously connected to while online. You must first connect to this reader or any reader of the same type while online. Or, if you want to connect while offline, you can connect to a reader type that your POS previously connected to while online. |
If you reinstall the application or perform any operation that clears the disk storage for the SDK, you lose any payments that the SDK has stored and not yet forwarded. Make sure there are no stored payments before you perform any destructive action.
Handle offline eventsClient-side
Implement the OfflineDelegate
protocol and pass it to Terminal to notify your application of offline-related events. You must set OfflineDelegate
before collecting payments offline.
You can also query Terminal.
to check the current network status of the SDK.
The SDK attempts to forward payments even if the network status is offline. This means your connection token provider might receive a request to provide a connection token, even if the SDK’s network status is offline. During payment collection, the network status determines if the SDK processes the payment online or immediately stores the payment.
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 stripeId
. We recommend adding a custom identifier to the PaymentIntent’s metadata to help reconcile PaymentIntent
objects created offline.
Within your OfflineDelegate.
callback, you can use your identifier to correlate offline payments with payments that are successfully forwarded to Stripe.
Managing risk while offline
The Terminal.
accepts a CreateConfiguration
parameter. By default, if you’re operating offline, the Terminal SDK 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 SDK has stored a set of transactions whose sum exceeds a certain amount.
The SDK exposes two properties to help you manage risk:
Terminal.
offlineStatus. sdk. offlinePaymentsCount Terminal.
offlineStatus. sdk. 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 SDK 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.
Use the didRequestReaderInput
method to display the valid card presentment options to the customer.
Using the initWithUpdatePaymentIntent
parameter in CollectConfiguration
is disabled when offline mode is enabled unless the 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 stripeId
. 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 Internet access is restored, the SDK automatically begins forwarding the stored offline payments.
If you power off your POS device too soon, your payments might not be forwarded. You can query Terminal.
to make sure your POS is online and can forward payments, and Terminal.
to check how many payments the Terminal SDK has to be forwarded.
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 RequiresCapture
. 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
OfflineDelegate.
for each PaymentIntent as the SDK forwards it. A PaymentIntent is ready to capture if its status isdidForwardPayment RequiresCapture
.
If your application determines when to capture a PaymentIntent after confirmPaymentIntent
, they’re ready to capture when the status is RequiresCapture
, and the offlineDetails
is null or has a requiresUpload
value of NO
.
Capture a payment after confirmPaymentIntent
, if it’s confirmed online:
Capture an offline payment after the SDK forwards it in your OfflineDelegate’s didForwardPaymentIntent
:
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.