Point of Sale SDK for iOS Reference

Point of Sale SDK

Point of Sale SDK for iOS Overview

The Square Point of Sale SDK for iOS is an Objective-C implementation of the Square Point of Sale API. Using the Point of Sale SDK instead of using the Point of Sale API directly can simplify the development process.

The Point of Sale SDK is available on Github, along with a helpful sample application that demonstrates its use.

To learn about the basics of the Point of Sale API, see Using the Point of Sale API.

Setting up

Before you can use the Point of Sale SDK, you need to complete the tasks described in the Build on iOS guide.

Initiating a transaction with Square Point of Sale

Initiating a Square Point of Sale transaction with the Point of Sale SDK takes two main steps:

  1. Create an SCCAPIRequest object with the details of the transaction you want to charge.
  2. Use the SCCAPIConnection class to send your SCCAPIRequest along to Square Point of Sale to be processed.

The following code snippet demonstrates generating an SCCAPIRequest object and sending it to Square Point of Sale:

    // Always set the client ID before creating your first API request.
    [SCCAPIRequest setClientID:@"YOUR_APPLICATION_ID"];

    // Replace with your app's callback URL.
    NSURL *const callbackURL = [NSURL URLWithString:@"my-point-of-sale-sdk-app://myCallback"];

    // Specify the amount of money to charge.
    SCCMoney *const amount = [SCCMoney moneyWithAmountCents:100 currencyCode:@"USD" error:NULL];

    // Specify which forms of tender the merchant can accept
    SCCAPIRequestTenderTypes const supportedTenderTypes = SCCAPIRequestTenderTypeAll;

    // Specify whether default fees in Square Point of Sale are cleared from this transaction
    // (Default is NO, they are not cleared)
    BOOL const clearsDefaultFees = YES;

    // Replace with any string you want returned from Square Point of Sale.
    NSString *const userInfoString = @"Useful information";

    // Replace with notes to associate with the transaction.
    NSString *const notes = @"Notes";

    // Initialize the request.
    NSError *error = nil;
    SCCAPIRequest *const request = [SCCAPIRequest requestWithCallbackURL:callbackURL
        amount:amount
        userInfoString:userInfoString
        locationID:nil
        notes:notes
        customerID:nil
        supportedTenderTypes:supportedTenderTypes
        clearsDefaultFees:clearsDefaultFees
        returnAutomaticallyAfterPayment:NO
        error:&error];

    // Perform the request.
    BOOL const success = [SCCAPIConnection performRequest:request error:&error];

Receiving data from Square Point of Sale

Square Point of Sale sends data back to your iOS app via the callbackURL you provide in your request. To receive the data, your app's UIApplicationDelegate needs to implement the application:openURL:options: method:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options {

      // Make sure that the URL comes from Square Point of Sale and fail if it doesn't
      if (![[options objectForKey:UIApplicationOpenURLOptionsSourceApplicationKey] hasPrefix:@"com.squareup.square"]) {
        return NO;
      }

      NSError *decodeError = nil;

      // Wrap the returned data in an SCCAPIResponse object
      SCCAPIResponse *const response = [SCCAPIResponse responseWithResponseURL:url error:&decodeError];

      // Process the response as desired

      return YES;
    }

See SCCAPIResponse for the fields included in Square Point of Sale's response.

Handling errors

The Point of Sale SDK can encounter an error at a few different points during the course of a payment:

Cause Result
An SCCAPIMoney object is created with invalid parameters. Error information is populated in the NSError object you provide when initializing the object. Possible error codes are described in SCCErrorCode.
The requestWithCallbackURL:amount:... method of SCCAPIRequest is called with invalid parameters. Error information is populated in the NSError object provided as a parameter to the requestWithCallbackURL:amount:... method. Possible error codes are described in SCCErrorCode.
The merchant encounters an error while processing a payment in Square Point of Sale. Error information is populated in the error property of the SCCAPIResponse object you generate from Square Point of Sale's callback to your app. Possible error codes are described in SCCAPIErrorCode.
An SCCAPIResponse object is created from an invalid URL. Error information is populated in the NSError object provided as a parameter to the responseWithResponseURL:error: method. Possible error codes are described in SCCErrorCode.

SCCAPIRequest Class Reference

Use this class to create a transaction request you send to Square Point of Sale. These are the core steps for creating a payment request:

  1. Use the setClientID class method to specify your Application ID for all subsequent requests.
  2. Create a new request with the requestWithCallbackURL... method.
  3. Send the request to Square Point of Sale with the performRequest:error: method of SCCAPIConnection.

Inherits from: NSObject

Conforms to: NSCopying

Properties

clientID

@property (nonatomic, copy, readonly, nonnull) NSString *clientID;

The Application ID to associate with this request. You set this value with the setClientID method before initializing an SCCAPIRequest object.

callbackURL

@property (nonatomic, copy, readonly, nonnull) NSURL *callbackURL;

The URL that Square Point of Sale will send its response to upon transaction completion.

amount

@property (nonatomic, copy, readonly, nonnull) SCCMoney *amount;

The amount of money to charge for the transaction.

userInfoString

@property (nonatomic, copy, readonly, nullable) NSString *userInfoString;

If you provide this value, it's passed along to your application's callback_url after the payment completes. Use this parameter to associate any helpful state information with the payment request.

locationID

@property (nonatomic, copy, readonly, nullable) NSString *locationID;

The ID of the business' location you want to associate the payment with. The Connect v2 RetrieveLocation endpoint returns a business' location IDs.

This ID must correspond to whichever location is currently logged in to Square Point of Sale. Otherwise, Square Point of Sale will respond with an error.

notes

@property (nonatomic, copy, readonly, nullable) NSString *notes;

A custom note to associate with the resulting transaction. Custom notes are displayed in the Square Dashboard and printed on receipts.

customerID

@property (nonatomic, copy, readonly, nullable) NSString *customerID;

The ID of the merchant's customer to link the payment with. The List Customers API Endpoint can be used to fetch a merchant's customers' IDs.

This ID must correspond to a customer in the merchant's customer directory. Otherwise, Square Point of Sale will respond with an error. An Internet connection is also required for Square Point of Sale to retrieve the customer's details for the specified customer ID. If there is no internet connection, the transaction will fail with an error.

supportedTenderTypes

@property (nonatomic, assign, readonly) SCCAPIRequestTenderTypes supportedTenderTypes;

The types of tender that Square Point of Sale is allowed to accept for the payment.

clearsDefaultFees

@property (nonatomic, assign, readonly) BOOL clearsDefaultFees;

If YES, default fees (i.e., taxes) are not automatically applied to the transaction in Square Point of Sale.

returnsAutomaticallyAfterPayment

@property (nonatomic, assign, readonly) BOOL returnsAutomaticallyAfterPayment;

If YES, Square Point of Sale automatically switches back to your app following a short timeout after the transaction completes. Otherwise, the merchant must tap the New Sale button in Square Point of Sale to return to your app.

Methods

+ requestWithCallbackURL:amount:userInfoString:locationID:notes:customerID:supportedTenderTypes:clearsDefaultFees:returnAutomaticallyAfterPayment:error:

Creates an SCCAPIRequest object that you can use to initiate a transaction with Square Point of Sale.

+ (nullable instancetype)requestWithCallbackURL:(nonnull NSURL *)callbackURL amount:(nonnull SCCMoney *)amount userInfoString:(nullable NSString *)userInfoString locationID:(nullable NSString *)locationID notes:(nullable NSString *)notes customerID:(nullable NSString *)customerID supportedTenderTypes:(SCCAPIRequestTenderTypes)supportedTenderTypes clearsDefaultFees:(BOOL)clearsDefaultFees returnAutomaticallyAfterPayment:(BOOL)autoreturn error:(out NSError *__nullable *__nullable)error;

Parameters
Name Type Description
callbackURL NSURL*

The URL that Square Point of Sale sends responses to. Must use the custom URL scheme you specified on your application settings.

amount SCCMoney

The amount of money to charge in the transaction.

userInfoString NSString*

If you provide this value, it's passed along to your callbackURL after the payment completes. Use this parameter to associate any helpful state information with the payment request.

locationID NSString*

The ID of the business' location you want to associate the card payment with. The Connect v2 RetrieveLocation endpoint returns a business' location IDs.

This ID must correspond to whichever location is currently logged in to Square Point of Sale. Otherwise, Square Point of Sale will respond with an error.

notes NSString*

A custom note to associate with the resulting transaction.

customerID NSString*

The ID of the merchant's customer to link the payment with. The List Customers API Endpoint can be used to fetch a saved customer profile ID.

This ID must correspond to a customer in the merchant's customer directory. Otherwise, Square Point of Sale will respond with an error.

An Internet connection is also required for Square Point of Sale to retrieve the customer's details for the specified customer ID. If there is no internet connection, the transaction will fail with an error.

supportedTenderTypes SCCAPIRequestTenderTypes

The types of tender that Square Point of Sale is allowed to accept for the payment.

clearsDefaultFees BOOL

If YES, default fees (i.e., taxes) are not automatically applied to the payment in Square Point of Sale.

returnsAutomaticallyAfterPayment BOOL

If YES, Square Point of Sale automatically switches back to your app following a short timeout after the transaction completes. Otherwise, the merchant must tap the New Sale button in Square Point of Sale to return to your app.

error NSError*

Stores an error in the event that an invalid parameter was provided.

setClientID:

Sets the clientID for all subsequent requests sent to Square Point of Sale. You must set this value before initiating any requests to Square Point of Sale.

+ (void)setClientID:(NSString *)clientID;

Parameters
Name Type Description
clientID NSString*

Your Connect API Application ID, available from your application dashboard.

- isEqualToAPIRequest:

Checks whether the values of this SCCAPIRequest are identical to those of another.

- (BOOL)isEqualToAPIRequest:(nullable SCCAPIRequest *)request;

Parameters
Name Type Description
request SCCAPIRequest*

The SCCAPIRequest object to compare to this one.

Return Value

YES if this object and request are logically equivalent. NO otherwise.

SCCAPIConnection Class Reference

Sends transaction requests to Square Point of Sale for processing.

Inherits from: NSObject

Methods

+ canPerformRequest:error:

Checks whether a version of Square Point of Sale is installed on the device that can accept a provided Point of Sale API request.

+ (BOOL)canPerformRequest:(nonnull SCCAPIRequest *)request error:(out NSError *__nullable *__nullable)error;

Parameters
Name Type Description
request SCCAPIRequest

The request to check.

error NSError*

Stores an error in the event that there is not a version of Square Point of Sale installed on the device that can accept request. See SCCErrorCode for possible values for code.

Return Value

YES if the request can be performed. NO otherwise.

+ performRequest:error:

Sends a transaction request to the Square Point of Sale app for processing.

+ (BOOL)performRequest:(nonnull SCCAPIRequest *)request error:(out NSError *__nullable *__nullable)error;

Parameters
Name Type Description
request SCCAPIRequest

The request to send along to Square Point of Sale for processing.

error NSError*

Stores an error in the event that the transaction request failed. See SCCErrorCode for possible values for code.

Return Value

YES if the request was successfully sent. NO otherwise.

SCCAPIResponse Class Reference

Create an instance of this class (with the responseWithResponseURL:error: method) for easy access to the values provided by Square Point of Sale's callback to your app. These values summarize the result of an SCCAPIRequest your app sent to Square Point of Sale. This is an immutable value type.

Inherits from: NSObject

Conforms to: NSCopying

Properties

transactionID

@property (nonatomic, copy, readonly, nullable) NSString *transactionID;

The ID of the transaction generated by Square's servers, if the transaction was successfully processed online. Otherwise, nil.

You can use this ID to get the full details of the transaction with the RetrieveTransaction endpoint of the Square Connect API.

clientTransactionID

@property (nonatomic, copy, readonly) NSString *clientTransactionID;

The transaction's unique client ID, generated by the Square Point of Sale app. This value is generated for bookkeeping purposes, in case the transaction cannot immediately be completed.

If the transaction was done in offline mode or asynchronously (e.g., for cash or other tender transactions), the server-generated transactionID may not be available immediately. Developers can use this value to cross-reference this response with transactions retrieved via the Connect API. This value corresponds to the client_id field in the Connect V2 Transaction object.

Note that it is not currently possible to perform a transaction lookup by this value using the Connect API.

error

@property (nonatomic, copy, readonly, nullable) NSError *error;

Contains details of the error that occurred during the request, if any. Otherwise, nil.

userInfoString

@property (nonatomic, copy, readonly, nullable) NSString *userInfoString;

The value you provided for userInfoString in your SCCAPIRequest, if any. This value is returned even if an error occurred during the request.

Methods

+ responseWithResponseURL:error:

Constructs an SCCAPIResponse object from a response URL provided by Square Point of Sale.

+ (nullable instancetype)responseWithResponseURL:(nonnull NSURL *)URL error:(out NSError *__nullable *__nullable)error;

Parameters
Name Type Description
URL NSURL*

The URL provided by Square Point of Sale's callback.

error NSError*

Stores an error in the event that URL is not a valid API response.

Return Value

An instance of SCCAPIResponse if URL is a valid API response. Otherwise, nil.

- isEqualToAPIResponse:

Checks whether the values of this SCCAPIResponse are identical to those of another.

- (BOOL)isEqualToAPIResponse:(nullable SCCAPIResponse *)response;

Parameters
Name Type Description
response SCCAPIResponse*

The SCCAPIResponse object to compare to this one.

Return Value

YES if this object and response are logically equivalent. NO otherwise.

SCCMoney Class Reference

Represents an amount of money to process with Square Point of Sale.

Inherits from: NSObject

Conforms to: NSCopying

Properties

amountCents

@property (nonatomic, assign, readonly) NSInteger amountCents;

The amount of money, in the smallest unit of the applicable currency. For US dollars, this value is in cents.

currencyCode

@property (nonatomic, copy, readonly, nonnull) NSString *currencyCode;

The currency of the monetary amount. The currency code for US dollars is USD.

Methods

+ moneyWithAmountCents:currencyCode:error:

Returns an instance of an SCCMoney object.

+ (nullable instancetype)moneyWithAmountCents:(NSInteger)amountCents currencyCode:(nonnull NSString *)currencyCode error:(out NSError *__nullable *__nullable)error;

Parameters
Name Type Description
amountCents NSInteger

The amount of money, in the smallest unit of the applicable currency. For US dollars, this value is in cents.

currencyCode NSString*

The currency of the monetary amount. The currency code for US dollars is USD.

error NSError*

Stores an error in the event that amountCents or currencyCode is invalid.

- isEqualToSCCMoney:

Checks whether the amount and currency code of this SCCMoney object are both equal to another.

- (BOOL)isEqualToSCCMoney:(nullable SCCMoney *)money;

Parameters
Name Type Description
money SCCMoney*

The SCCMoney object to compare to this one.

Return Value

YES if this object and money are logically equivalent. NO otherwise.

Point of Sale SDK Tender Types

SCCAPIRequestTenderTypes

Use these tender types when initializing an SCCAPIRequest to designate the payment methods that will appear in Square Point of Sale. This enum is an NS_OPTIONS bitmask, so you can choose any number of them when creating your request.

Value Description
SCCAPIRequestTenderTypeAll

Allow the merchant to accept all API-supported tender types to complete the payment.

SCCAPIRequestTenderTypeCard

Allow the merchant to accept card tenders to complete the payment.

Note: Japanese sellers can accept E-money payments from Transportation IC, QUICPay, and iD with this enumeration.

SCCAPIRequestTenderTypeCash

Allow the merchant to accept other tenders to complete the payment.

SCCAPIRequestTenderTypeOther

Allow the merchant to accept other tenders to complete the payment.

SCCAPIRequestTenderTypeSquareGiftCard

Allow the merchant to accept Square gift cards to complete the payment.

SCCAPIRequestTenderTypeCardOnFile

Allow the merchant to accept customer cards on file to complete the payment.

SCCAPIRequestTenderTypePayPay

Allow the merchant to accept Square customers' PayPay tender to complete the payment.

Point of Sale SDK Error Codes

SCCAPIErrorCode

These error codes are returned by Square Point of Sale if an error occurs during a transaction. They belong to the SCCAPIErrorDomain domain.

Value Description
SCCAPIErrorCodeUnknown

An unknown error occurred.

SCCAPIErrorCodeClientNotAuthorizedForUser

Point of Sale versions prior to 4.53 require the developer to guide merchants through OAuth before allowing them to take payments with Point of Sale API. As of Point of Sale 4.53, this error type is deprecated.

SCCAPIErrorCodePaymentCanceled

The merchant canceled the payment in Square Point of Sale.

SCCAPIErrorCodePayloadMissingOrInvalid

The URL sent to Square Point of Sale had missing or invalid information.

SCCAPIErrorCodeAppNotLoggedIn

A merchant is not currently logged in to Square Point of Sale.

SCCAPIErrorCodeLocationIDMismatch

The business location currently logged in to Square Point of Sale does not match the location represented by the location_id you provided in your request.

SCCAPIErrorCodeUserNotActivated

The currently logged in location has not activated card processing.

SCCAPIErrorCodeCurrencyMissingOrInvalid

The currency code provided in the request is missing or invalid.

SCCAPIErrorCodeCurrencyUnsupported

The currency code provided in the request is not currently supported in the Point of Sale API.

SCCAPIErrorCodeCurrencyMismatch

The currency code provided in the request does not match the currency associated with the current business.

SCCAPIErrorCodeAmountMissingOrInvalid

The request had a missing or invalid amount to charge.

SCCAPIErrorCodeAmountTooSmall

The request's amount to charge was too small.

SCCAPIErrorCodeAmountTooLarge

The request's amount to charge was too large.

SCCAPIErrorCodeInvalidTenderType

The request included an invalid tender type.

SCCAPIErrorCodeUnsupportedTenderType

The request included a tender type that is not currently supported by the Point of Sale API.

SCCAPIErrorCodeCouldNotPerform

The SCCAPIConnection was unable to perform the request.

SCCAPIErrorCodeNoNetworkConnection

The transaction failed because the device has no network connection.

SCCAPIErrorCodeUnsupportedAPIVersion

The API version specified in the request is not supported by the installed version of Square Point of Sale.

SCCAPIErrorStringInvalidVersionNumber

The API version specified in the request is not in a form that Square Point of Sale recognizes. Version numbers must be in standard decimal form (e.g., 1.3).

SCCAPIErrorStringCustomerManagementNotSupported

This merchant account does not support customer management and therefore cannot associate transactions with customers.

SCCAPIErrorStringInvalidCustomerID

The customer_id you provided in your request does not correspond to any customer in the merchant's customer directory.

SCCErrorCode

These errors are returned by Point of Sale SDK classes during instantiation or various method calls. They belong to the SCCErrorDomain domain.

Value Description
SCCErrorCodeUnknown

An unknown error occurred.

SCCErrorCodeMissingCurrencyCode

No currency code was specified.

SCCErrorCodeUnsupportedCurrencyCode

An unsupported currency code was specified.

SCCErrorCodeMissingRequestClientID

No value was provided for the clientID parameter in the request.

SCCErrorCodeInvalidRequestCallbackURL,

An invalid value was provided for the callbackURL parameter.

SCCErrorCodeInvalidRequestAmount

An invalid value was provided for the amount parameter.

SCCErrorCodeCannotPerformRequest

The request could not be performed.

SCCErrorCodeUnableToGenerateRequestJSON

The SCCAPIRequest could not be converted to valid JSON.