Point of Sale SDK

    // 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];

- (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;
    }

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

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

- isEqualToAPIRequest:

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

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

Parameters

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

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

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

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

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

- isEqualToSCCMoney:

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

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

Parameters

Return Value

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