Authorize your Android Application

To enable your application to securely connect to a 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 of 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 if you want to collect application fees.

The Mobile Payments SDK is divided into four managers to provide specific areas of functionality. Authorization is handled by the AuthorizationManager. Use authorizationManager.authorize() to authorize your Mobile Payments SDK application with a Square seller's accessToken and locationId. You also pass in a callback to be notified of authorization errors and successes and display those to the user.

override fun onResume() {
    super.onResume()
    val authorizationManager = MobilePaymentsSdk.authorizationManager()
    // Authorize and handle authorization successes or failures
    callbackReference = authorizationManager.authorize(accessToken, locationId) { result ->
        when (result) {
            is Success -> {
                finishWithAuthorizedSuccess(result.value)
            }
            is Failure -> {
                when (result.errorCode) {
                    NO_NETWORK -> // show error message and retry suggestion
                        ...
                    USAGE_ERROR -> // show error message
                        ...
                }
            }
        }
    }
}

override fun onPause() {
    super.onPause()
    // Remove the callback reference to prevent memory leaks
    callbackReference?.clear()
}

You can check whether a user of your application is currently authorized by checking AuthorizationState.isAuthorized() prior to beginning authorization.

To track changes in the authorization state, register a callback by using authorizationManager.setAuthorizationStateChangedCallback(). This callback can give you live updates to the authorizationManager.authorizationState 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. If the SDK detects an expired token, it deauthorizes the Square seller account and invokes the callback registered with setAuthorizationStateChangedCallback with AuthorizationState(isAuthorized = false, isAuthorizationInProgress = false).

To deauthorize the Mobile Payments SDK and log out of a seller's Square account, use authorizationManager.deauthorize(). This method provides a completion handler, called when the SDK finishes deauthorizing.

The seller remains authorized as long as their access token is valid. Therefore, it is a good idea to call this method when a user logs out of your application or has not had any activity within a period of time. This prevents your application from tracking a large number of dangling authorizations. Calling authorizationManager.deauthorize() doesn't expire a user's OAuth access token, it only deauthorizes the user from the mobile device running the Mobile Payments SDK.

After authorizing your application, you're ready to pair a card reader and prepare to start taking payments.