Square’s own developer site

Configure app security on Square developer portal here.

Security is via a combination of iOS App Bundle ID, iOS App URL Scheme & Application ID all of these need to be registered with Square and are validated on each transaction.

TAAP RN F2f Digital Wallet Design Docs

Square (Point of Sale) API

Square use a very similar method to the well established X-callback-uri scheme. There are some subtle changes which are outlined below.

The mobile app needs to package a request JSON object with the following required information and send it to the Square Point of Sale API.

• Total amount — The total transaction amount represented in the smallest unit of the supplied currency. For example a value of 100 corresponds to 1 GBP.
• Currency code — The currency code of the transaction, e.g., GBP
• Tender types — The tender types allowed as payment. The selected tender types are displayed by the Square Point of Sale app during payment processing
• Callback URL — The callback URI that Square Point of Sale will use to pass results back to the merchant mobile app
• Application ID — The Square-issued application ID of the merchant mobile app
• API version — The targeted version of the Square Point of Sale API, e.g., v2.0.
  The Square Point of Sale API receives a request object with transaction information and opens the Point of Sale app pre-populated
• A note to be associated with the transaction
• Reference information that is returned when the transaction completes
• A Square customer ID to be associated with the transaction

Mobile apps package transaction information and send it to the Square Point of Sale app. The Point of Sale API uses URLs with custom schemes to communicate between mobile web apps and the Square Point of Sale app. Square Point of Sale accepts URLs with the scheme square-commerce-v1 and sends transaction results back to the calling app using the URL scheme. Mobile web apps open the Point of Sale API by opening a URL with parameters that contain the required information.

Square API callback [aka Point of Sale API] square-commerce-v1://payment/create?data=_encoded_json_object_ where _encoded_json_object_ is the URL encoded JSON for

{
  "client_id": "sq0idp--yBrrSEQw_FhsXAuJqVh2Q",
  "sdk_version": "3.1",
  "amount_money": {
    "amount": 100,
    "currency_code": "GBP"
  },
  "callback_url": "taapmobilewallet://callback",
  "options": {
    "auto_return": true,
    "clear_default_fees": false,
    "supported_tender_types": ["CREDIT_CARD"]
  },
  "version": "1.3"
}

"amount":100 = £1.00 (Which is the minimum amount)

Example good call

square-commerce-v1://payment/create?data=%7B%22client_id%22%3A%22sq0idp--yBrrSEQw_FhsXAuJqVh2Q%22%2C%22sdk_version%22%3A%223.1%22%2C%22amount_money%22%3A%7B%22amount%22%3A100%2C%22currency_code%22%3A%22GBP%22%7D%2C%22callback_url%22%3A%taapmobilewallet%3A%5C%2F%5C%2Fcallback%22%2C%22options%22%3A%7B%22auto_return%22%3Atrue%2C%22clear_default_fees%22%3Afalse%2C%22supported_tender_types%22%3A%5B%22CREDIT_CARD%22%5D%7D%2C%22version%22%3A%221.3%22%7D

which will return (Via the URL scheme)

taapmobilewallet://callback?data=%7B%22status%22:%22ok%22,%22transaction_id%22:%22eqGc0S2KCT0eZ5Nd1Aefp68eV%22,%22client_transaction_id%22:%22E945ABE4-26B9-4754-BE16-54B34E0970E4%22%7D

which decodes as:

{
  "status": "ok",
  "transaction_id": "eqGc0S2KCT0eZ5Nd1Aefp68eV",
  "client_transaction_id": "E945ABE4-26B9-4754-BE16-54B34E0970E4"
}

Example failed return call.

taapmobilewallet://callback?data=%7B%22error_code%22:%22payment_canceled%22,%22status%22:%22error%22%7D

Which decodes to:

{
  "error_code": "payment_canceled",
  "status": "error"
}

cf:

• Square Developer Portal
• TAAP F2F Contactless App Link
• Square GitHub iOS example.

Process Flow

1. The merchant mobile app determines the total amount to charge a customer
2. The merchant mobile app packages the transaction information and sends it in a request to the Square Point of Sale app
3. The mobile device running the merchant mobile app automatically opens the Square Point of Sale app
4. The charge amount is pre-populated in the Square Point of Sale app based on the provided transaction information
5. The transaction is completed with the Square Point of Sale app checkout flow
6. The Square Point of Sale app sends completed transaction information to the provided callback URL
7. The device reactivates the merchant mobile app to receive and display the transaction results

If the payment is successful, the Point of Sale app response includes a transaction ID and tender IDs that can be used with other Square Connect APIs to pull more information or issue refunds at a later date. Failed or canceled payment results include an error code indicating why the request failed. All callbacks include any reference information packaged with the original checkout flow request.

iOS App URL Scheme

The URL scheme(s) are defined as part of the application’s info.plist.

  ...
  <key>CFBundleURLTypes</key>
  <array>
    <dict>
      <key>CFBundleURLName</key>
      <string>com.ontaap.f2f-mobile-wallet</string>
      <key>CFBundleURLSchemes</key>
      <array>
        <string>taapmobilewallet</string>
      </array>
    </dict>
  </array>
  ...

And add the following to AppDeligate.m (or it’s equivalent).

Static Site Parameters

See the static site’s README for design documentation etc.