Authorize the Mobile Payments SDK

To enable your application to securely connect to any Square seller account, the Mobile Payments SDK must be authorized using an OAuth access token and a location ID. Each Square seller who uses your application must be authorized with an OAuth access token The same process should be used even if you only plan to use the Mobile Payments SDK with your own Square account. To get started, see OAuth documentation and OAuth sample applications.

When requesting an OAuth access token from a seller, your application must request the following permissions:

• MERCHANT_PROFILE_READ is required to get a list of all a seller's locations.
• PAYMENTS_WRITE and PAYMENTS_WRITE_IN_PERSON are required to take payments with the Mobile Payments SDK.
• PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS is required only if you want to collect application fees.

When displaying the Square authorization page, it’s recommended to use SFSafariViewController instead of WKWebView. WKWebView can be used if it's required for the look and feel of your application, but using SFSafariViewController is a more supported and stable experience. For information about when to use SFSafariViewController rather than WKWebView, see Apple's guidance.

The Mobile Payments SDK is divided into four managers to provide specific areas of functionality. Authorization is handled by the AuthorizationManager. In your application's authorization or bootstrapping logic, use the authorizationManager authorize() function to authorize the Mobile Payments SDK with the OAuth access token and location ID for the Square seller connecting to your application. When authorization completes, the AuthorizeCompletionHandler provides the result of the authorization, including any errors.

import SquareMobilePaymentsSDK

class <#YourViewController#>: UIViewController {
    func authorizeMobilePaymentsSDK(accessToken: String, locationID: String) {
        guard MobilePaymentsSDK.shared.authorizationManager.state == .notAuthorized else {
            return
        }

        MobilePaymentsSDK.shared.authorizationManager.authorize(
           withAccessToken: accessToken,
            locationID: locationID) { error in
                guard let authError = error else {
                    print("Square Mobile Payments SDK successfully authorized.")
                    return
                }

                // Handle auth error
                print("error: \(authError.localizedDescription)")
        }
    }
}

You can check whether a user of your application is authorized, notAuthorized, or (in the process of) authorizing by checking AuthorizationManager.state prior to beginning authorization. However, this value isn't modified if the state changes.

To asynchronously track changes in the authorization state, add an AuthorizationStateObserver to your viewController to receive updates to the authorization state whenever the Mobile Payments SDK is authorized or deauthorized.

Square OAuth access tokens expire after 30 days. After expiration, applications must generate a new OAuth access token using the refresh token received when the authorization was first granted. The response looks like the following:

{
  "access_token": "EAAAEL_l5ncx260W8yWz2gGO0GtJeFBJqIdHIXZjpQZ_XW-yxh-Tl7MlF8vIE__n",
  "token_type": "bearer",
  "expires_at": "2024-05-15T19:36:00Z",
  "merchant_id": "TVSNN09QQY609",
  "refresh_token": "EQAAEInZRUFx8bgauwrDjXYIioyCDEB7vyOG0cScx-qfczgTpNtUjAGLResAKOe9"
}

Square recommends tracking the expires_at value on your server and refreshing the authorization token before it expires. You can store expiration time on the device and check it during application initialization.

The Mobile Payments SDK also performs checks for an expired authorization token during initialization and application startup and if pairing a card reader fails. If the SDK detects an expired token, it deauthorizes the Square seller account (in the same manner as calling AuthorizationManager.deauthorize()) and your AuthorizationStateObserver is notified of the change in state.

To deauthorize the Mobile Payments SDK and sign out of a seller's Square account, use the Authorization Manager's deauthorize() method. This method provides a DeauthorizeCompletionHandler, called when the SDK finishes deauthorizing.

It's a good idea to call this method regularly, when a user logs out of your application or hasn't had any activity within a period of time. This prevents your application from having to track a large number of dangling authorizations.

func deauthorizeMobilePaymentsSDK() {
 MobilePaymentsSDK.shared.authorizationManager.deauthorize {
   // Check authorization status
   print(MobilePaymentsSDK.shared.authorizationManager.state)
 }
}

After the Mobile Payments SDK is installed and initialized in your mobile application and authorized with a Square account, you're ready to pair and manage card readers.