Take Payments

Mobile Authorization API Guide

Authorize custom apps to take in-person payments with Square hardware.

The Mobile Authorization API lets developers request authorization tokens to initialize mobile solutions like Reader SDK.

Requirements and limitations

  • The Mobile Authorization API accepts requests through HTTPS and TLS 1.2. Connections through HTTP are not supported.
  • The Mobile Authorization API is not supported in the Square sandbox. See the Square Testing Guide for alternative recommendations.

How it works — Mobile Authorization API process flow

The Mobile Authorization API accepts an account credential (OAuth token or Personal Access Token) and location ID and returns an authorization code that custom mobile apps can use to initialize Square mobile solutions like Reader SDK to accept payments using Square hardware. In general, requesting a mobile authorization code involves the following steps:

  1. The mobile app calls the custom authorization service.
  2. The authorization service completes Square's OAuth flow and obtains a valid OAuth token.
  3. The authorization service uses the Locations API to call the ListLocations endpoint and gather a list of locations associated with the target account.
  4. The authorization service API selects a target Location ID programmatically or with a web UI.
  5. The authorization service calls CreateMobileAuthorizationCode with the OAuth token and selected Location ID.
  6. The authorization service returns a mobile authorization code to the mobile app.
Mobileauthz process flow

Mobile Authorization API Setup

To embed Square mobile development solutions (e.g., Reader SDK), you must create a service to request mobile authorization codes. We recommend integrating this into your existing OAuth process if possible.

Assumptions

The sample code in this guide makes the following assumptions:

  • The authorization service uses PHP version 5.4 or later. We use PHP for example code because it is a common web language and relatively approachable for new developers, but Square APIs are language agnostic and the setup steps are comparable across languages.
  • The authorization service uses the Square Connect v2 PHP SDK. Installing the SDK is optional. As long as you can package and receive JSON messages you can use Square APIs, but installing the SDK makes things easier.

Step 1: Add code to request an OAuth token

Add code to construct an OAuth request with the following permissions:

  • PAYMENTS_WRITE_IN_PERSON — required to process payments on behalf of the target Square account.
  • MERCHANT_PROFILE_READ — required to access location IDs for the target account through the Connect API.
  • PAYMENTS_READ — required to access transaction and refund details for the target account through the Connect API.
  • PAYMENTS_WRITE — required to issue refunds on behalf of the target account through the Connect API.
$applicationId = '{APPLICATION ID FOR MOBILE APP BEING AUTHORIZED}';
$squareDomain = "https://connect.squareup.com";
$oauthAuthorizePath = "/oauth2/authorize";
$mobileAuthzScope = urlencode(
                "PAYMENTS_WRITE_IN_PERSON " .
                "MERCHANT_PROFILE_READ " .
                "PAYMENTS_READ " .
                "PAYMENTS_WRITE"
              );

$authzURL = $squareDomain .
            $oauthAuthorizePath .
            "?client_id=" . $applicationId .
            "&scope=" . $mobileAuthzScope;

Make sure that the OAuth token used to obtain a mobile authorization code belongs to the Square Application used to integrate with Square mobile solutions (e.g., Reader SDK).

See the OAuth Setup Guide for more information on handling the OAuth callback and exchanging the OAuth code for a valid OAuth token.

Step 2: Get a valid location ID

  1. Use the OAuth token from Step 1 to create and configure a default API client:
// Create and configure a new Configuration object with the OAuth token
$configuration = new \SquareConnect\Configuration() ;
$configuration->setAccessToken($oauthToken) ;
$apiClient = new \SquareConnect\ApiClient($configuration) ;
  1. Create a Locations API client and select a target location:
// Create a LocationsApi client and grab the target location ID
$locClient = new \SquareConnect\Api\LocationsApi($apiClient) ;
$apiResponse = $locClient->listLocations()->getLocations() ;
foreach ($apiResponse as $location) {
  if ($location->getName() == "{TARGET LOCATION NAME}") {
    $targetLocationId = $location['id'] ;
  }
}

The code above selects a location ID based on the associated store name. Alternatively, you could present a list of locations in the browser and have the user select the location to use. For example:

<form action='{FORM SUBMISSION TARGET}' method='POST'>
  <input type='hidden' id='locationId' value=''>

<? foreach ($apiResponse as $location) { ?>
  <input
    type='submit'
    name='selectLocation'
    onclick='document.getElementById("locationId").value = "<?=$location->getId()?>"'
    value='<?=$location->getName()?>'
  ></input><br>

<? } ?>
</form>

Step 3: Request a mobile authorization code

Lastly, add code to use the location ID and OAuth token to request a mobile authorization code. The authorization service should return the mobile authorization code to the calling application but for the sake of this example, we will simply print it to the screen.

// Create a MobileAuthorizationApi client to request an authorization code
$mobileAuthzClient = new \SquareConnect\Api\MobileAuthorizationApi($apiClient) ;
$body = new \SquareConnect\Model\CreateMobileAuthorizationCodeRequest();
$body->setLocationId($targetLocationId);
$apiResponse = $mobileAuthzClient->CreateMobileAuthorizationCode($body);
$mobileCode = $apiResponse->getAuthorizationCode();

echo "Mobile authz code:" . $mobileCode;

Request a mobile authorization code with cURL

We recommend generating mobile authorization codes programmatically because they are short-lived and cannot be hardcoded and reused. But it may be necessary to generate a mobile authorization code manually during development.

To generate a mobile authorization code manually:

  1. Open the Square Application Dashboard.
  2. Copy your Personal Access Token from the Credentials page.
  3. Copy an active Location ID from the Locations page.
  4. Paste the values into the following cURL command:
curl https://connect.squareup.com/mobile/authorization-code \
  -H 'Content-Type: application/json'                       \
  -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'     \
  -d '{"location_id":"YOUR_LOCATION_ID"}'

You should get a response that looks like this:

squareup.com/mobile/authorization-code
{
  "authorization_code": "YOUR_MOBILE_AUTHORIZATION_CODE",
  "expires_at": "2018-05-11T02:05:07Z"
}
Next
Reader SDK Overview >

Ask for help on Stack Overflow or join our Slack channel