Offline Payments

The Mobile Payments SDK supports taking payments in offline mode, for example 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.

• 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 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.
• If you're using the Mobile Payments SDK with a Square Reader for contactless and chip, both a bluetooth connection and a secure connection are required to take offline payments.
  • Bluetooth connection relies on device settings and physical distance. A reader must maintain a Bluetooth connection with a mobile device's POS application to take payments.
  • A secure connection is established when a reader is connected to a mobile device that has its POS application open and online.

To take offline payments with the Mobile Payments SDK and a bluetooth Square reader:

• The reader must be connected to a device that was online and had its POS application opened within the last 24 hours.
• The POS device must have a bluetooth connection to the reader and have offline processing enabled before going offline.
• The reader must maintain a bluetooth connection to your device throughout the offline payment.

At this time, the Offline Payments feature for the Mobile Payments SDK is in Beta and requires Square sellers to opt in to this feature. If a seller using your application is interested in taking payments offline with the Mobile Payments SDK, 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 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 merchantNotOptedIntoOfflineProcessing error.

Each seller taking payments offline with the Mobile Payments SDK 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 the limit for a single transaction, the Mobile Payments SDK returns an offlineTransactionAmountExceeded error. If your application attempts to take an offline payment that exceeds the allowed offline payment total, the SDK returns an offlineStoredAmountExceeded 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.

let paymentSettings = MobilePaymentsSDK.shared.settingsManager.paymentSettings

let isOfflineProcessingAllowed = paymentSettings.isOfflineProcessingAllowed
let offlineTransactionAmountLimit = paymentSettings.offlineTransactionAmountLimit
let offlineTotalStoredAmountLimit = paymentSettings.offlineTotalStoredAmountLimit

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 availableCardInputMethods() and display the possible payment methods to customers.

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 onlineOnly, 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 offlineOnly. 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 autoDetect. In this case, the SDK checks the status of the local network connection and the performance of Square's servers before processing the payment.

let paymentParams = PaymentParameters(
   idempotencyKey: UUID().uuidString,
   amountMoney: Money(amount: 100, currency: .USD)
)

// Force offline processing of payments
paymentParams.processingMode = .offlineOnly

let paymentHandle = MobilePaymentsSDK.shared.paymentManager.startPayment(
   paymentParams,
   promptParameters: PromptParameters(
      mode: .default,
      additionalMethods: .all
   ),
   from: self,
   delegate: self
)

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 Square Dashboard.

let offlinePaymentQueue = MobilePaymentsSDK.shared.paymentManager.offlinePaymentQueue

// Grab total amount stored 
offlinePaymentQueue.getTotalStoredPaymentsAmount { [weak self] money, error in
   guard let self else { return }

   if let error {
      print("Error getting total stored payments amount: \(error)")
      return
   }

   print("Total stored amount: \(money.amount)")
}

// Grab offline payments
offlinePaymentQueue.getPayments { [weak self] offlinePayments, error in
   guard let self else { return }

   if let error {
      print("Error getting offline payments: \(error)")
      return
   }

   // Get the total number of payments currently stored
   let totalNumberOfPayments = offlinePayments.count

   // Iterate over the offline payments
   offlinePayments.forEach { offlinePayment in
      switch offlinePayment.status {
      case .queued:
         // Payment is retained on the local device; awaiting upload by Mobile Payments SDK.
         break
      case .uploaded:
         // Payment has been successfully uploaded to the Square Server.
         break
      case .failedToUpload:
         // Upload of payment failed due to an unrecoverable error.
         break
      case .failedToProcess:
         // Processing of offline payment by Square Server failed, possibly due to card decline or other transaction issue.
         break
      case .processed:
         // Offline payment has been successfully processed by Square Server and is now visible in the merchant dashboard.
         break
      case .unknown:
         fallthrough
      @unknown default:
         // The status is unknown; verification could not be completed.
         break
      }
   }
}

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.

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 Square Dashboard and the payment can be accessed and managed by the Payments API after this processing is complete.

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.