Register SDK for iOS Reference

Register SDK

Register SDK for iOS Overview

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

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

To learn about the basics of the Register API, see Using the Register API.

Setting up

Before you can use the Register SDK, you need to complete the tasks described in the Register API setup section of Using the Register API.

Initiating a transaction with Square Register

Initiating a Square Register transaction with the Register 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 Register to be processed.

The following code snippet demonstrates generating an SCCAPIRequest object and sending it to Square Register:

// 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-register-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 Register 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 Register.
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
                                                          merchantID: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 Register

Square Register 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 Register 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 Register's response.

Handling errors

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

CauseResult
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 Register.Error information is populated in the error property of the SCCAPIResponse object you generate from Square Register'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 Register. 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 Register 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 Register 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.

merchantID

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

The ID of the business' location you want to associate the payment with. This code sample demonstrates fetching a business' location IDs.

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

notes

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

A custom note to associate with the resulting transaction.

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 Register will respond with an error. An Internet connection is also required for Square Register 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 Register 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 Register.

returnsAutomaticallyAfterPayment

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

If YES, Square Register 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 Register to return to your app.

Methods

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

Creates an SCCAPIRequest object that you can use to initiate a transaction with Square Register.

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

Parameters
NameTypeDescription
callbackURLNSURL*

The URL that Square Register sends responses to. Must use the custom URL scheme you specified on your application dashboard.

amountSCCMoney

The amount of money to charge in the transaction.

userInfoStringNSString*

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.

merchantIDNSString*

The ID of the business' location you want to associate the card payment with. This code sample demonstrates fetching a business' location IDs.

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

notesNSString*

A custom note to associate with the resulting transaction.

customerIDNSString*

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 Register will respond with an error.

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

supportedTenderTypesSCCAPIRequestTenderTypes

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

clearsDefaultFeesBOOL

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

returnsAutomaticallyAfterPaymentBOOL

If YES, Square Register 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 Register to return to your app.

errorNSError*

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

setClientID:

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

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

Parameters
NameTypeDescription
clientIDNSString*

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
NameTypeDescription
requestSCCAPIRequest*

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 Register for processing.

Inherits from: NSObject

Methods

+ canPerformRequest:error:

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

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

Parameters
NameTypeDescription
requestSCCAPIRequest

The request to check.

errorNSError*

Stores an error in the event that there is not a version of Square Register 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 Register app for processing.

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

Parameters
NameTypeDescription
requestSCCAPIRequest

The request to send along to Square Register for processing.

errorNSError*

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 Register's callback to your app. These values summarize the result of an SCCAPIRequest your app sent to Square Register. 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 Register 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 Register.

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

Parameters
NameTypeDescription
URLNSURL*

The URL provided by Square Register's callback.

errorNSError*

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
NameTypeDescription
responseSCCAPIResponse*

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 Register.

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
NameTypeDescription
amountCentsNSInteger

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

currencyCodeNSString*

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

errorNSError*

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
NameTypeDescription
moneySCCMoney*

The SCCMoney object to compare to this one.

Return Value

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

Register SDK Tender Types

SCCAPIRequestTenderTypes

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

ValueDescription
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.

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.

Register SDK Error Codes

SCCAPIErrorCode

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

ValueDescription
SCCAPIErrorCodeUnknown

An unknown error occurred.

SCCAPIErrorCodeClientNotAuthorizedForUser

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

SCCAPIErrorCodePaymentCanceled

The merchant canceled the payment in Square Register.

SCCAPIErrorCodePayloadMissingOrInvalid

The URL sent to Square Register had missing or invalid information.

SCCAPIErrorCodeAppNotLoggedIn

A merchant is not currently logged in to Square Register.

SCCAPIErrorCodeMerchantIDMismatch

The business location currently logged in to Square Register does not match the location represented by the merchant_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 Register 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 Register 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 Register.

SCCAPIErrorStringInvalidVersionNumber

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

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 Register SDK classes during instantiation or various method calls. They belong to the SCCErrorDomain domain.

ValueDescription
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.