Offline Payments (Alpha)

Link to section


The Mobile Payments SDK supports taking payments in offline mode, which allows you to take payments when a reader is used in a location with weak network connection or the application momentarily loses connection to Square servers. Offline payments are stored (queued) locally on the mobile device running the Mobile Payments SDK application and processed by Square the next time the device successfully connects to the Internet and Square servers.

Link to section

Requirements and limitations

  • Offline payments aren't supported in the Square Sandbox.
  • Interac debit cards don't work in Offline mode. Any offline transaction attempted with an Interac debit card auto-decline when regaining connectivity.
  • Your application must be connected to the Internet to connect a new Square reader. If you intend to take offline payments, Square recommends pairing any reader devices while online.
  • Offline Payments Alpha support is limited to the two most recent versions of Square Reader for contactless and chip, Square Reader for magstripe, and Square Stand second generation. To learn whether your reader device is supported, see Hardware devices and capabilities.


The Square seller is responsible for any expired, declined, or disputed payments accepted while offline. By providing their merchant ID to participate in the Alpha program, the seller is aware of and accepting this risk.

Before upgrading to a new version of the Mobile Payments SDK or a new version of your application, you should upload all offline payments and verify that the offline payment queue is empty.

Link to section

Alpha onboarding

At this time, the Offline Payments feature for the Mobile Payments SDK is in private Alpha. Square sellers must opt in to this feature. If a seller using your application is interested in joining the Offline Payments Alpha, send an email to [email protected]. In your message, include:

  • The seller's business name.
  • The seller's email address (this should be the owner or administrator for the seller's Square account).
  • Your application ID.

Square contacts the seller directly and provides them with a seller onboarding form for this Alpha feature. After the seller is successfully onboarded, Square sends you (the developer) a confirmation email letting you know that you can accept offline payments for the seller.

At any time, you can check the isOfflineProcessingAllowed value within the PaymentSettings to determine whether the seller that is authorized with your application can take payments offline. If your application tries to take an offline payment for a seller who doesn't have access to this feature, you receive a USAGE_ERROR.

Link to section

Transaction limits

Each seller participating in the Offline Payments Alpha has a limit on each offline payment and a limit to the total amount they can store offline on their mobile device. These limits vary by seller. If your application attempts to take an offline payment that exceeds one of these limits, the Mobile Payments SDK returns a USAGE_ERROR.

Each device running the Mobile Payments SDK can take up to 1000 payments for up to 24 hours before reconnecting to the network. If this limit is reached, the reader fails to connect and your mobile device must connect to a network to process and upload these payments before accepting more.

val paymentSettings = MobilePaymentsSdk.settingsManager().getPaymentSettings() val isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed val offlineTransactionAmountLimit = paymentSettings.offlineTransactionAmountLimit val offlineTotalStoredAmountLimit = paymentSettings.offlineTotalStoredAmountLimit
Link to section

Payment methods

The payment methods available to customers are limited while offline and not all devices support every type of offline payment. Before taking any payment, your application should query the Payment Manager's getavailableCardEntryMethods() and display the possible payment methods to customers.

Link to section

Take a payment offline

When you're ready to take a payment with the Mobile Payments SDK, you create PaymentParameters with details about the payment. The processingMode field determines whether the payment should be taken offline. By default, each payment's processing mode is ONLINE_ONLY, meaning the payment can only be processed using a network call.

In some situations, such as when a location has a sporadic or weak Internet connection, sellers might want to take all payments offline during a period of time. To do so, set the processingMode for payments to OFFLINE_ONLY. All payments made with this mode are initially queued on the mobile device, even if there is a network connection.

Alternatively, you can set the processingMode for payments to AUTO_DETECT. In this case, the SDK checks the status of the local network connection and the performance of Square's servers before processing the payment.

val paymentManager = MobilePaymentsSdk.paymentManager() val baseMoney = Money(100L, USD) val builder = PaymentParameters.Builder( amount = baseMoney, idempotencyKey = UUID.randomUUID().toString(), ).processingMode(ProcessingMode.OFFLINE_ONLY) val paymentParameters = val promptParameters = PromptParameters( mode = PromptMode.DEFAULT, additionalPaymentMethods = listOf(Type.KEYED) ) viewModel.startPaymentActivity(paymentParameters, promptParameters)


When an offline payment is queued, it hasn't yet been processed by Square. The transaction isn't returned from the ListPayments endpoint and doesn't have a Square payment ID value. If your application's workflow involves delayed payment capture or syncing Square payments with an outside transaction database, you must write logic to query Square for the completed payment and its details and then perform that sync. For more information, see Payment IDs.

Link to section

Access offline payments

The Mobile Payments SDK provides the getOfflinePaymentQueue() method in the Payment Manager to access all payments taken offline by the application on the current mobile device. This includes queued payments waiting to be processed and completed processed payments. Only payments that have a locationId matching the current application user's location ID are returned. This prevents two Square sellers logging in to your application on the same mobile device from viewing each other's payments.

The status of an OfflinePayment indicates its current point in the payment workflow and whether it failed to upload or process. The status can be one of the following:

  • QUEUED - The payment is stored locally on the device running the Mobile Payments SDK application. The SDK attempts to upload the payment to Square after the network connection is restored.
  • UPLOADED - The payment has been uploaded to the Square server, but hasn't yet been processed.
  • FAILED_TO_UPLOAD - The payment couldn't be uploaded due to an unrecoverable error.
  • FAILED_TO_PROCESS - The connection was restored, but Square couldn't process this specific offline payment. This might be because of a declined card or another error with the card-issuing bank. An offline payment with this status cannot be recovered, and the seller doesn't receive funds from the transaction.
  • PROCESSED - Square processed your offline payment successfully. It can now be seen in the Seller Dashboard.
Link to section

Payment IDs

A payment taken offline with the Mobile Payments SDK has two identification values: localID, used to identify the payment on your mobile device before it's processed, and id, which represents the Square payment id value. The second value is always null until the SDK uploads the payment to Square and the payment is processed.

When a payment's status changes to PROCESSED, you can access its id value from the mobile device and match it to the id value of payments returned by the ListPayments endpoint. You can now continue your application's payment workflow and use other Square APIs to access and manage the payment. PROCESSED payments are deleted from the mobile device to conserve storage space.

Link to section

Process offline payments

The Mobile Payments SDK regularly checks for network connectivity and a connection to Square servers so that queued payments can be processed. This is done automatically while the application is open in the foreground of the device. Assuming that there are no errors in the PaymentParameters or issues like cards being declined, the funds are available to the seller in the Seller Dashboard and the payment can be accessed and managed by the Payments API after this processing is complete.


The following actions result in queued payments being removed from the device. If this happens before the payment is uploaded and processed, it cannot be processed and the seller doesn't receive funds from the transaction:

  • Wiping the device cache
  • Authenticating the Mobile Payments SDK with a different application ID on the same device
  • Uninstalling the application from the device using the Mobile Payments SDK

Queued payments remain on the device when a user force-quits your application, switches to another application, or a seller logs out of your application. As a best practice, your application should query for any QUEUED payments on the device before calling authorizationManager.deauthorize(), so that you can alert the seller about any unprocessed payments.