Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
4 contributors

Users who have contributed to this file

@hukid @goblinhorde @SudoPlz @okenshields
753 lines (574 sloc) 25 KB

React Native Reader SDK Technical Reference

This technical reference documents methods available in the React Native wrapper for Reader SDK. For detailed documentation on Reader SDK, please see docs.connect.squareup.com.



Methods at a glance

Method Return Object Description
authorizeAsync Location Authorizes Reader SDK to collect payments.
canDeauthorizeAsync boolean Verifies Reader SDK can be deauthorized.
deauthorizeAsync void Deauthorizes Reader SDK.
getAuthorizedLocationAsync Location Returns the currently authorized location
isAuthorizedAsync boolean Verifies Reader SDK is currently authorized for payment collection.
isAuthorizationInProgressAsync boolean Verifies Reader SDK is currently authorizing.
startCheckoutAsync CheckoutResult Begins the checkout workflow.
startReaderSettingsAsync void Starts the Reader settings flow for connecting Square Reader

Method details

authorizeAsync

Used to authorize Reader SDK to collect payments on behalf of a Square location.

Parameter Type Description
authCode string Authorization code from the Mobile Authorization API

Example usage

import {
  authorizeAsync,
  AuthorizeErrorNoNetwork,
  UsageError,
} from 'react-native-square-reader-sdk';
...
try {
  const authorizedLocation = await authorizeAsync(authCode);
  // Authorized and authorizedLocation is available
} catch(ex) {
  switch(ex.code) {
    case AuthorizeErrorNoNetwork:
      // Remind connecting to network
      break;
    case UsageError:
      let errorMessage = ex.message;
      if (__DEV__) {
        errorMessage += `\n\nDebug Message: ${ex.debugMessage}`;
        console.log(`${ex.code}:${ex.debugCode}:${ex.debugMessage}`)
      }
      Alert.alert('Error', errorMessage);
      break;
  }
}

canDeauthorizeAsync

Used to determine if it is safe to deauthorize Reader SDK.

  • On success: returns true if all transactions have successfully synced to Square, false otherwise.
  • On failure: throws USAGE_ERROR.

Example usage

import { canDeauthorizeAsync } from 'react-native-square-reader-sdk';
...
if (await canDeauthorizeAsync()) {

  // Handle deauthorization

} else {
  Alert.alert('Unable to deauthorize', 'You cannot deauthorize right now.');
}

deauthorizeAsync

Used to deauthorize Reader SDK. Reader SDK cannot be deauthorized if there are transactions that have not been synced to Square.

Example usage

import { deauthorizeAsync } from 'react-native-square-reader-sdk';
...
try {
  await deauthorizeAsync();
  // Deauthorize finished successfully
} catch(ex) {
  let errorMessage = ex.message;
  if (__DEV__) {
    errorMessage += `\n\nDebug Message: ${ex.debugMessage}`;
    console.log(`${ex.code}:${ex.debugCode}:${ex.debugMessage}`)
  }
  Alert.alert('Error', errorMessage);
}

getAuthorizedLocationAsync

Used to fetch information about the location currently authorized for Reader SDK.

  • On success: returns information about the currently authorized location as a Location object.
  • On failure: throws USAGE_ERROR.

Example usage

import { getAuthorizedLocationAsync } from 'react-native-square-reader-sdk';
...

try {
  const authorizedLocation = await getAuthorizedLocationAsync();
  // Start using the location object
} catch (ex) {
  let errorMessage = ex.message;
  if (__DEV__) {
    errorMessage += `\n\nDebug Message: ${ex.debugMessage}`;
    console.log(`${ex.code}:${ex.debugCode}:${ex.debugMessage}`)
  }
  Alert.alert('Error', errorMessage);
}

isAuthorizedAsync

Used to determine if Reader SDK is currently authorized to accept payments.

Example usage

import { isAuthorizedAsync } from 'react-native-square-reader-sdk';
...
if (await isAuthorizedAsync()) {

  // Ready to take payments

} else {
  Alert.alert('Unable to take payments', 'Reader SDK is not authorized.');
}

isAuthorizationInProgressAsync

Used to determine if Reader SDK is currently authorizing.

  • On success: returns true if the sdk is currently authorizing, false otherwise.
  • On failure: throws USAGE_ERROR.

Example usage

import { isAuthorizationInProgressAsync } from 'react-native-square-reader-sdk';
...
if (await isAuthorizationInProgressAsync()) {

  // The reader is currently authorizing, don't try to authorize again

} else {
  Alert.alert('Unable to authorize again', 'Reader SDK is already authorizing.');
}

startCheckoutAsync

Used to start the checkout flow and collect payment information from Square Reader. Checkout cannot be started from a modal screen.

Parameter Type Description
checkoutParams CheckoutParameter Configures the checkout flow and transaction amount.

Example usage

import {
  startCheckoutAsync,
  CheckoutErrorCancelled,
  CheckoutErrorSdkNotAuthorized,
  UsageError,
} from 'react-native-square-reader-sdk';
...
try {
  const checkoutResult = await startCheckoutAsync(checkoutParams);
  // checkout finished successfully and checkoutResult is available
} catch(ex) {
  switch(ex.code) {
    case CheckoutErrorCanceled:
      // Handle canceled transaction here
      break;
    case CheckoutErrorSdkNotAuthorized:
      // Handle sdk not authorized
      break;
    default:
      let errorMessage = ex.message;
      if (__DEV__) {
        errorMessage += `\n\nDebug Message: ${ex.debugMessage}`;
        console.log(`${ex.code}:${ex.debugCode}:${ex.debugMessage}`)
      }
      Alert.alert('Error', errorMessage);
      break;
  }
}

startReaderSettingsAsync

Used to start the Reader settings flow. Returns an error if Reader SDK is not currently authorized.

Example usage

import {
  startReaderSettingsAsync,
  ReaderSettingsErrorSdkNotAuthorized,
  UsageError,
} from 'react-native-square-reader-sdk';
...
try {
  await startReaderSettingsAsync();
} catch (ex) {
  switch(ex.code) {
    case ReaderSettingsErrorSdkNotAuthorized:
      // Handle reader settings not authorized
      break;
    case UsageError:
      let errorMessage = ex.message;
      if (__DEV__) {
        errorMessage += `\n\nDebug Message: ${ex.debugMessage}`;
        console.log(`${ex.code}:${ex.debugCode}:${ex.debugMessage}`)
      }
      Alert.alert('Error', errorMessage);
      break;
  }
}

startStoreCardAsync

Used to start the store a card for a customer flow.

The card information is stored on Square servers, not on the specific device running Reader SDK. This means cards cannot be saved on file when offline, and that saved cards for a customer are available from any device, keyed by customer ID.

Example usage

import {
  startStoreCardAsync,
  StoreCustomerCardCancelled,
  StoreCustomerCardInvalidCustomerId,
  StoreCustomerCardSdkNotAuthorized,
  StoreCustomerCardNoNetwork,
  UsageError,
} from 'react-native-square-reader-sdk';
...
const customerId = 'DRYKVK5Y6H5R4JH9ZPQB3XPZQC';
try {
  const card = await startStoreCardAsync(customerId);
  // Customer's card is stored successfully and card infomation is available
} catch (ex) {
  let errorMessage = ex.message;
  switch (ex.code) {
    case StoreCustomerCardCancelled:
      // Handle canceled
      break;
    case StoreCustomerCardInvalidCustomerId:
      // Handle invalid customer id error
      break;
    case StoreCustomerCardNoNetwork:
      // Handle no network error
      break;
    case StoreCustomerCardSdkNotAuthorized:
      // Handle sdk not authorized
      break;
    default:
      if (__DEV__) {
        errorMessage += `\n\nDebug Message: ${ex.debugMessage}`;
        console.log(`${ex.code}:${ex.debugCode}:${ex.debugMessage}`);
      }
      Alert.alert('Error', errorMessage);
      break;
  }
}

Objects

Card

Represents the non-confidential details of a payment card.

Field Type Description
brand CardBrand Indicates the entity responsible for issuing the card.
lastFourDigits String Indicates how the card information was captured.
expirationMonth integer The month when the associated card expires, if available. Expiration month is always an integer between 1 and 12, inclusive.
expirationYear integer The 4-digit year when the associated card expires, if available.
id String The unique, Square-issued identifier for the card. Only set when the object represents a saved card on file.
cardholderName String The cardholder name. This value is present only if this object represents a customer’s card on file.

Example JSON

{
  "brand": "VISA",
  "lastFourDigits": "1111",
  "expirationMonth": 10,
  "expirationYear": 2019,
  "id": "ccof:GrUQnrDgWnQIK6tp3GB",
  "cardHolderName": "Tod Hu"
}

CardDetails

Contains details related to a card tender used in a successful checkout flow.

Field Type Description
entryMethod EntryMethod Indicate how the card information was captured.
card Card Provides information about the card used for payment.

Example JSON

{
  "entryMethod": "MANUALLY_ENTERED",
  "card": {
    "brand": "VISA",
    "lastFourDigits": "1111"
  }
}

CashDetails

Contains details related to a cash tender used in a successful checkout flow.

Field Type Description
buyerTenderMoney Money The total payment amount provided as cash during checkout.
changBackMoney Money The total change provided as cash during checkout.

Example JSON

{
  "buyerTenderMoney": {
    "currencyCode": "USD",
    "amount": 110
  },
  "changBackMoney": {
    "currencyCode": "USD",
    "amount": 10
  }
}

CheckoutParameter

Configures the UI experience for the checkout flow.

Field Type Description
amountMoney Money REQUIRED. The total payment amount.
skipReceipt boolean Indicates that the digital receipt options screen should not be displayed during checkout. Default: false
collectSignature boolean Indicates that signature collection is required during checkout. When false, the signature screen will never be displayed; when true, it will always be used. Default: false
allowSplitTender boolean Indicates that multiple payment methods are allowed. Default: false
delayCapture boolean When true, if checkout completes successfully, the SDK will only authorize,but not capture any card payments. You can then use the Square Connect CaptureTransaction endpoint to capture the card payments at a later time. Setting delayCapture to true will skip the receipt, tipping, and signature screens, and the following parameters will be ignored: tipSettings, skipReceipt, collectSignature. Default: false. By default, the SDK will immediately capture all card payments.
note String A note to display on digital receipts and in the Square Dashboard. Default: undefined (empty note)
tipSettings TipSettings Settings that configure the tipping behavior of the checkout flow. Default: undefined (Tip screen disabled)
additionalPaymentTypes AdditionalPaymentType[] Valid payment methods for checkout (in addition to payments via Square Readers). Default: undefined (No additional payment method)

Example JSON

{
  "amountMoney": {
    "amount": 1000,
    "currencyCode": "USD"
  },
  "skipReceipt": false,
  "collectSignature": true,
  "allowSplitTender": false,
  "delayCapture": false,
  "note": "Payment for dogsitting",
  "tipSettings": {
    "showCustomTipField": "false",
    "showSeparateTipScreen": "true",
    "tipPercentages": [10, 15, 20]
  },
  "additionalPaymentTypes": ["cash", "manual_card_entry", "other"]
}

CheckoutResult

Contains the result of a successful checkout flow.

Field Type Description
totalMoney Money The total amount of money collected during the checkout flow.
locationId String The unique ID of the location to which the transaction was credited.
totalTipMoney Money The total tip amount applied across all tenders.
transactionClientId String A unique client-generated ID.
createdAt String The date and time when the transaction was completed as determined by the client device.
tenders Tender[] The set of tenders associated with a successful transaction.
transactionId String A unique ID issued by Square. Only set for successful transactions that include one or more card tenders.

All successful transactions include a client-generated ID (transactionClientId). Transactions with card tenders also include a transactionId that is assigned when the card is processed by Square.

To reconcile transactions that do not have card tenders, use transactionClientId to match client-generated transactions to the client_id field in transactions returned by the ListTransactions endpoint of the Transactions API.

Example JSON

{
"totalMoney": {
  "currencyCode": "USD",
  "amount": 100
},
"locationId": "XXXXXXXXXXXXX",
"totalTipMoney": {
  "currencyCode": "USD",
  "amount": 0
},
"tenders": [
  {
    "type": "cash",
    "createdAt": "2018-08-22T18:05:18Z"
  },
  {
    "type": "card",
    "tenderId": "XXXXXXXXXXXXXXXXXXXXXXXX",
    "createdAt": "2018-08-22T18:05:59Z"
  },
],
  "transactionId": "XXXXXXXXXXXXXXXXXXXXXXXX",
  "transactionClientId": "0X0000X0-0000-000X-XX0X-X00XX00X00X0",
  "createdAt": "2018-08-22T18:05:21Z"
}

Location

Represents information about a location associated with a Square account.

Field Type Description
currencyCode String The currency used for all transactions at this location, specified in ISO 4217 format .
businessName String The business name associated with the location. This is the name shown on Square digital receipts.
isCardProcessingActivated boolean Indicates whether or not this location is activated for card processing.
maximumCardPaymentAmountMoney Money The maximum card payment amount allowed at this location.
minimumCardPaymentAmountMoney Money The minimum card payment amount allowed at this location.
name String The nickname of the location as set in the Square Dashboard.
locationId String A unique ID for the location assigned by Square

Example JSON

{
  "currencyCode": "USD",
  "businessName": "Raphael's Puppy Care Emporium",
  "isCardProcessingActivated": true,
  "maximumCardPaymentAmountMoney": {
    "amount": 50000,
    "currencyCode": "USD"},
  "minimumCardPaymentAmountMoney": {
    "amount": 100,
    "currencyCode": "USD"},
  "name": "Chicago Treat-mobile",
  "locationId": "XXXXXXXXXXXXX"
}

Money

Captures information about the amount tendered during a transaction. Monetary amounts are specified, in the smallest denomination of the currency indicated. For example, when currency is USD, amount is in cents, so a 1 dollar payment (1 USD) would have amount equal to 100.

Field Type Description
amount integer REQUIRED The amount of money, in the smallest denomination of the indicated currency.
currencyCode string The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

All Money objects require an amount and currencyCode but currenyCode is optional for the Reader SDK React Native plugin because Money objects will use the currency code of the currently authorized location by default.

Example JSON

{
  "amount": 100,
  "currencyCode": "USD"
}

Tender

Contains the result of a processed tender.

Field Type Description
cardDetails CardDetails Details about the tender. Only set for card tenders.
cashDetails CashDetails Details about the tender. Only set for cash tenders.
createdAt String The date and time when the tender was processed as determined by the client device.
tenderId String A unique ID issued by Square. Only set for card tenders.
tipMoney Money The monetary amount added to this tender as a tip.
totalMoney Money The total monetary amount of this tender, including tips.
type TenderType The method used to make payment.

Example JSON

{
  "type": "cash",
  "tenderId": "XXXXXXXXXXXXXXXXXXXXXXXX",
  "createdAt": "2018-08-22T18:05:18Z",
  "totalMoney": {
    "amount": 1500,
    "currencyCode": "USD"
  },
  "tipMoney": {
    "amount": 500,
    "currencyCode": "USD"
  },
  "cashDetails": {
    "buyerTenderMoney": {
      "currencyCode": "USD",
      "amount": 2000
    },
    "changBackMoney": {
      "currencyCode": "USD",
      "amount": 500
    }
  }      
}

TipSettings

Settings that configure the tipping behavior of the checkout flow.

Field Type Description
showCustomTipField boolean Indicates whether custom tip amounts are allowed during the checkout flow. Default: false.
showSeparateTipScreen boolean Indicates that tip options should be presented on their own screen. Default: false.
tipPercentages Integer[] A list of up to 3 non-negative integers from 0 to 100 (inclusive) to indicate tip percentages that will be presented during the checkout flow. Default: [15, 20, 25]

Example JSON

{
  "showCustomTipField": "false",
  "showSeparateTipScreen": "true",
  "tipPercentages": [10, 15, 20]
}

Constants

AdditionalPaymentType

Payment types accepted during the Reader SDK checkout flow in addition to payments via Square Readers:

  • card - Manually typed-in card payments.
  • cash - Cash payments. Useful for testing.
  • other - Check, third-party gift cards, and other payment types.

CardBrand

Supported brands for card payments accepted during the Reader SDK checkout flow.

  • VISA - Visa Inc. credit or debit card.
  • MASTERCARD - Mastercard Incorporated credit or debit card.
  • AMERICAN_EXPRESS - merican Express Company credit card.
  • DISCOVER - Discover Financial Services credit card.
  • DISCOVER_DINERS - Diners Club International credit card.
  • INTERAC - Canadian Interbank Network debit card.
  • JCB - Japan Credit Bureau credit card.
  • CHINA_UNIONPAY - China UnionPay credit card.
  • SQUARE_GIFT_CARD - Square-issued gift card.
  • EFTPOS - A debit or cash-back transaction (Electronic Funds Transfer at Point Of Sale).
  • OTHER_BRAND - An unexpected card type.

EntryMethod

Entry methods for card payments accepted during the Reader SDK checkout flow.

  • CHIP - Card information collected with Square Reader via chip ("dip").
  • CONTACTLESS - Card information collected with Square Reader via NFC ("tap").
  • MANUALLY_ENTERED - Card information collected by typing it in ("keyed-in").
  • SWIPE - Card information collected with Square Reader via magstripe ("swipe").
  • UNKNOWN - iOS only. Card information collected in some other way (e.g., Apple Pay digital wallet).

TenderType

Methods used to provide payment during a successful checkout flow:

  • card - Scanned, dipped, or manually typed-in card payments.
  • cash - Cash payments. Useful for testing.
  • other - Check, third-party gift cards, and other payment types.

Errors

Error Cause Returned by
USAGE_ERROR Reader SDK was used in an unexpected or unsupported way. all methods
AUTHORIZE_NO_NETWORK Reader SDK could not connect to the network. authorizeAsync
CHECKOUT_CANCELED The user canceled the checkout flow. startCheckoutAsync
CHECKOUT_SDK_NOT_AUTHORIZED The checkout flow started but Reader SDK was not authorized. startCheckoutAsync
READER_SETTINGS_SDK_NOT_AUTHORIZED The Reader settings flow started but Reader SDK was not authorized. startReaderSettingsAsync
STORE_CUSTOMER_CARD_CANCELED The user canceled the store card flow. startStoreCardAsync
STORE_CUSTOMER_CARD_INVALID_CUSTOMER_ID The customer ID passed into the controller was invalid. startStoreCardAsync
STORE_CUSTOMER_CARD_SDK_NOT_AUTHORIZED The flow to store a customer card started but Reader SDK was not authorized. startStoreCardAsync
STORE_CUSTOMER_CARD_NO_NETWORK Reader SDK could not connect to the network. startStoreCardAsync
You can’t perform that action at this time.