Build on Mobile Web

Applies to: Point of Sale API - iOS | Point of Sale API - Android

Learn how to open the Square Point of Sale application from a custom mobile web application to process in-person payments using Square hardware.

• You've read the introductory review of this API.

• You're familiar with basic web development. If you're new to web development, you should read Getting started with the Web by Mozilla.org before continuing.

• You can create and run websites on localhost or a development server. If you're new to testing web pages locally, you should read Testing for supported countries before continuing.

• You're familiar with HTTP and JSON.

• You're building a mobile web application for POS transactions. If you're building a native mobile application, see Build on Android or Build on iOS.

• The mobile web application uses JavaScript and HTML.

Install the latest version of the Square Point of Sale application from the Google Play Store (Android) or the Apple App Store (iOS).

You need to go into the Developer Console and set the callback URL in the application. Your callback URL is where the Point of Sale API sends notifications and payment information. For example:

https://your-web-app.com/path/to/your/callback/

Note that /path/to/your/callback should be the path to the code that processes notifications and transaction information received from the Square Point of Sale application.

To register your callback URL:

1. In the Developer Console, choose your application, and then choose Point of Sale API in the left pane.
2. In the Web section, enter your Web Callback URL.
3. Choose Save.

Mobile web transactions are initiated by choosing a link to the Square Point of Sale application. Because the request URL includes details about the transaction, you should build the URL dynamically instead of hardcoding it. The link URL includes the transaction information as parameters and is formatted differently for Android and iOS applications.

Square Point of Sale application request URLs for Android are formatted as intent requests. For example:

<a href="intent:#Intent;
    action=com.squareup.pos.action.CHARGE;
    package=com.squareup;
    S.browser_fallback_url=https://my.website.com/index.html;
    S.com.squareup.pos.WEB_CALLBACK_URI=https://my.website.com/index.html;
    S.com.squareup.pos.CLIENT_ID=sq0ids-yourClientId;
    S.com.squareup.pos.API_VERSION=v2.1;
    i.com.squareup.pos.TOTAL_AMOUNT=100;
    S.com.squareup.pos.CURRENCY_CODE=USD;
    S.com.squareup.pos.TENDER_TYPES=com.squareup.pos.TENDER_CARD,com.squareup.pos.TENDER_CASH;
    end">Start Transaction</a>

Android requires URLs to be wrapped with Android start and end tokens when they contain key-value pairs delimited with semicolons. The Android start and end tokens are intent:#Intent; and end.

To build your request URL:

1. Create a JavaScript file called open_pos.js.

2. Add code to define some useful constants, configure your mobile web application, and set the transaction total.

// The URL where the Point of Sale app will send the transaction results.
var callbackUrl = "{YOUR CALLBACK URL}";

// Your application ID
var applicationId = "{YOUR APPLICATION ID}";

// The total and currency code should come from your transaction flow.
// For now, we are hardcoding them.
var transactionTotal = "{TRANSACTION TOTAL}";
var currencyCode = "USD";

// The version of the Point of Sale API that you are using.
var apiVersion = "v2.1";

3. Add code to build the request URL. For a detailed list of all possible URL parameters, see Mobile Web Technical Reference.

function openURL(){
  // Configure the allowable tender types
  var tenderTypes =
   "com.squareup.pos.TENDER_CARD, \
    com.squareup.pos.TENDER_CARD_ON_FILE, \
    com.squareup.pos.TENDER_CASH, \
    com.squareup.pos.TENDER_OTHER";

  var posUrl =
    "intent:#Intent;" +
    "action=com.squareup.pos.action.CHARGE;" +
    "package=com.squareup;" +
    "S.com.squareup.pos.WEB_CALLBACK_URI=" + callbackUrl + ";" +
    "S.com.squareup.pos.CLIENT_ID=" + applicationId + ";" +
    "S.com.squareup.pos.API_VERSION=" + apiVersion + ";" +
    "i.com.squareup.pos.TOTAL_AMOUNT=" + transactionTotal + ";" +
    "S.com.squareup.pos.CURRENCY_CODE=" + currencyCode + ";" +
    "S.com.squareup.pos.TENDER_TYPES=" + tenderTypes + ";" +
    "end";

  window.open(posUrl);
}

4. Add the following script tag to your HTML head to load your open_pos.js file:

<head>
  <!-- Loads callback javascript -->
  <script type="text/javascript" src="/open_pos.js"></script>
</head>

5. Add a button to your mobile web application that runs open_pos.js.

<button onclick="openURL()">
Start Transaction
</button>

To initiate a Square Point of Sale transaction from your website, call the Square Point of Sale application with a URL using the following format:

square-commerce-v1://payment/create?data={REPLACE ME}

1. Add code to create a percent-encoded JSON object that contains the information that the Square Point of Sale application needs to process the transaction request.

<script>
  var dataParameter = {
    amount_money: {
      amount:        "500",
      currency_code: "USD"
    },

    // Replace this value with your application's callback URL
    callback_url: "https://www.example.com",

    // Replace this value with your application's ID
    client_id: "MY_APPLICATION_ID",

    version: "1.3",
    notes: "notes for the transaction",
    options: {
      supported_tender_types: [
        "CARD_FROM_READER",
        "KEYED_IN_CARD",
        "CASH",
        "OTHER",
        "SQUARE_GIFT_CARD",
        "CARD_ON_FILE"
      ]
    }
  };

  window.location =
    "square-commerce-v1://payment/create?data=" +
    encodeURIComponent(JSON.stringify(dataParameter));
</script>

When the transaction finishes, the Square Point of Sale application returns to your registered callback URL with the transaction results. Android returns individual query parameters, while iOS returns a JSON object in the data query parameter.

Create a file called callback.html that loads callback.js and calls printResponse():

<html>
  <head>
    <script type="text/javascript" src="/callback.js"></script>
  </head>
  <body onload="printResponse()">
    <h1>Callback</h1>
    <pre id="url"></pre>
  </body>
</html>

Create callback.js, then add the code for your platform.

const clientTransactionId = "com.squareup.pos.CLIENT_TRANSACTION_ID";
const transactionId = "com.squareup.pos.SERVER_TRANSACTION_ID";
const errorField = "com.squareup.pos.ERROR_CODE";
const errorDescription = "com.squareup.pos.ERROR_DESCRIPTION";

function getUrlParams(url) {
  return Object.fromEntries(new URL(url).searchParams.entries());
}

function handleSuccess(transactionInfo) {
  let resultString = "";

  if (clientTransactionId in transactionInfo) {
    resultString += "Client Transaction ID: " + transactionInfo[clientTransactionId] + "\n";
  }
  if (transactionId in transactionInfo) {
    resultString += "Transaction ID: " + transactionInfo[transactionId] + "\n";
  } else {
    resultString += "Transaction ID: PROCESSED OFFLINE OR NO CARD USED\n";
  }
  return resultString;
}

function handleError(transactionInfo) {
  return "Error: " + transactionInfo[errorField] + " - " +
    (transactionInfo[errorDescription] || "No error description returned");
}

function printResponse() {
  const callbackUrl = window.location.href;
  const transactionInfo = getUrlParams(callbackUrl);
  const resultString = errorField in transactionInfo
    ? handleError(transactionInfo)
    : handleSuccess(transactionInfo);

  document.getElementById("url").textContent = resultString;
}

const callbackUrl =
  "https://your-web-app.com/callback" +
  "?com.squareup.pos.SERVER_TRANSACTION_ID=transaction123" +
  "&com.squareup.pos.CLIENT_TRANSACTION_ID=client-transaction-40";

For more information about Android and iOS callback fields and error codes, see Mobile Web Technical Reference.

Your application should keep track of whether a Point of Sale API request has been issued and whether a callback has been received. Because of the constraints of application-switching APIs, sellers can leave Square Point of Sale during an API request and return to your application. It's your responsibility to direct them to return to Square and finish the transaction.

1. Initialize the Point of Sale application before testing your first transaction:
   1. Sign in to the Square Point of Sale application with the business location and employee you want to accept payments.
   2. If you're using the Square Contactless and Chip Reader, connect it to the Square Point of Sale application. You get an error if you call the Point of Sale API without initializing the Point of Sale application first.
2. Open your web application in an emulator or on your mobile device, and then choose Start transaction to open the Point of Sale application.
3. To test the cancellation callback, cancel the transaction in the Point of Sale application.
4. To test the success callback, complete a cash payment, and then choose the checkmark to indicate you're done.

You cannot install the Square Point of Sale application on a virtual Xcode machine. For this reason, you need to test your code on a real iOS device. You can test your code that processes the data by creating a test response URL instead of receiving it from Square.