Build on iOS
Build with In-App Payments SDK on iOS to provide a secure, managed payments client.
Information you need
To use the example code in this guide, make sure you have the following information available:
Your application ID. Find your application ID on the Credentials page of your Square application in the Developer Dashboard.
An active location ID. Copy a valid Developer Account location ID from the Locations page of your Square application in the Developer Dashboard, or set the Developer Dashboard to Sandbox Settings mode and then copy a Sandbox location ID.
Important
While In-App Payments SDK supports payments for physical and digital sales, using In-App Payments SDK to process digital sales might not be allowed by some mobile application distribution services (such as, App Store and Google Play) and might result in your application being removed. Examples of digital sales include intangible goods (such as, in-game assets), online services (such as, upgrades in application functionality), and digital subscriptions (such as, cloud or streaming services).
To avoid the potential removal from application distribution platforms, In-App Payments SDK should only be used to process sales of goods or services that are consumed outside the application. You should review the terms of service for the respective mobile application distribution services you use to ensure that you are compliant with their guidelines.
Step 1: Set your Square application ID in your application delegate
Update REPLACE_ME in the following code with your Square application ID. If you do not set your Square application ID before initializing SQIPCardEntryViewController, your application terminates with an uncaught exception.
Important
To test an application in the Square Sandbox, set the Developer Dashboard to Sandbox Settings mode before completing the following instructions in this step.
@import SquareInAppPaymentsSDK;
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[SQIPInAppPaymentsSDK setSquareApplicationID:@"<# REPLACE_ME #>"];
return YES;
}
Note
When testing your application in the Square Sandbox, be sure to use Sandbox test values to enter card information.
Step 2: Set supported orientations for the card entry form
In-App Payments SDK supports all orientations on the iPad, but only supports portrait orientations on the iPhone.
If your application supports landscape on the iPhone, you should conform to
UINavigationControllerDelegate and override the supported interface orientations.
@interface <
#YourViewController #>() < UINavigationControllerDelegate> @end
@implementation <
#YourViewController #>
- (UIInterfaceOrientationMask)navigationControllerSupportedInterfaceOrientations : (
UINavigationController *)navigationController;
{ return UIInterfaceOrientationMaskPortrait; }
@end
Step 3: Create and display the card entry form to collect card information
Initialize a SQIPCardEntryViewController with a SQIPTheme instance and
present the view controller as a modal. You can customize the appearance of the
card entry form by setting SQIPTheme properties. For more information, see
Customize the Payment Entry Form.
Important
The card entry form should always be displayed in a UINavigationController.
@import SquareInAppPaymentsSDK;
@interface <
#YourViewController #>() < SQIPCardEntryViewControllerDelegate> @end
@implementation <
#YourViewController #>
- (void)showCardEntryForm;
{
SQIPTheme *theme = [[SQIPTheme alloc] init];
// Customize the card entry form
theme.tintColor = UIColor.greenColor;
theme.saveButtonTitle = @"Submit";
SQIPCardEntryViewController *cardEntryForm =
[[SQIPCardEntryViewController alloc] initWithTheme:theme];
cardEntryForm.delegate = self;
// The card entry form should always be displayed in a UINavigationController.
// The card entry form can also be pushed onto an existing navigation controller.
UINavigationController *navigationController =
[[UINavigationController alloc] initWithRootViewController:cardEntryForm];
[self presentViewController:navigationController animated:YES completion:nil];
}
#pragma mark - SQIPCardEntryViewControllerDelegate
- (void)cardEntryViewController:(nonnull SQIPCardEntryViewController *)cardEntryViewController
didCompleteWithStatus:(SQIPCardEntryCompletionStatus)status;
{
// Implemented in Step 4.
}
- (void)cardEntryViewController:(nonnull SQIPCardEntryViewController *)cardEntryViewController
didObtainCardDetails:(nonnull SQIPCardDetails *)cardDetails
completionHandler:(void (^_Nonnull)(NSError *_Nullable))completionHandler;
{
// Implemented in Step 4.
}
@end
Step 4: Implement SQIPCardEntryViewControllerDelegate methods
In this step, you implement the stubs you added previously.
Guidance for :didObtainCardDetails:completionHandler:
Use the card entry view controller delegate methods to complete payment processing after a buyer provides a payment card by submitting the nonce to your backend, awaiting a response, and then updating the mobile application with the results.
Submit the nonce to your backend. The handler is invoked after the buyer submits a payment card. Your code should send the provided card details to your backend to perform any additional work, such as charging the card. After your backend processes the card, notify the card entry view controller of the result so it can be displayed to the buyer.
Handle backend results. If your backend processes the card with no error, call the completion handler with a single
nilargument. A success animation is shown to the buyer andcardEntryViewController:didCompleteWithStatus:is called. At this point, you should dismiss the card entry view controller.Handle card processing errors. If your backend returns an error while processing the card, call the completion handler with the error. The
localizedDescriptionerror is shown in the card entry view controller. The buyer can read the error text, edit the entered card information, and then resubmit the payment.
#pragma mark - SQIPCardEntryViewControllerDelegate
- (void)cardEntryViewController:(nonnull SQIPCardEntryViewController *)cardEntryViewController
didObtainCardDetails:(nonnull SQIPCardDetails *)cardDetails
completionHandler:(void (^_Nonnull)(NSError *_Nullable))completionHandler;
{
// Send card nonce to your server to charge the card or store the card on file.
// When a response is received, call the completionHandler with `nil` for success,
// or an error to indicate failure.
/*
[MyAPIClient.shared chargeCardWithNonce:cardDetails.nonce
completion:^(id transaction, NSError *chargeError) {
if (chargeError) {
completionHandler(chargeError);
} else {
completionHandler(nil);
}
}];
*/
completionHandler(nil);
}
- (void)cardEntryViewController:(nonnull SQIPCardEntryViewController *)cardEntryViewController
didCompleteWithStatus:(SQIPCardEntryCompletionStatus)status;
{
// Note: If you pushed the card entry form onto an existing navigation controller,
// use [self.navigationController popViewControllerAnimated:YES] instead
[self dismissViewControllerAnimated:YES completion:nil];
}
Prerequisites and assumptions
To build with In-App Payments SDK on iOS, the following must be true:
The deployment target for your application is iOS 10.0 or newer.
You have added In-App-Payments SDK to your iOS project. For more information, see Install In-App-Payments SDK.
Additionally, this guide makes the following assumptions:
You have a Square account enabled for payment processing. If you have not enabled payment processing on your account (or you are not sure), visit squareup.com/activate.
You are generally familiar with developing applications on iOS. If you are new to iOS development, you should read The Basics at Swift.org.
You are using Xcode 9+.