In-App Payments SDK

Enable Apple Pay

Objective C (iOS)

Prerequisites and limitations Permalink Get a link to this section

To enable Apple Pay with In-App Payments SDK on iOS, the following must be true:

  • You are a US-based, Canadian, or UK-based Square seller. Apple Pay for In-App Payments SDK is only available for Square sellers based in Canada, the United States and the United Kingdom.

  • You have followed the instructions in the In-App Payments: Build on iOS guide. This guide does not cover the general setup of In-App Payments SDK.

  • You have added your Apple developer account to Xcode.

  • The deployment target for your application is iOS 10.0 or newer.

Step 1: Upload an Apple Pay certificate to the Square Developer Dashboard Permalink Get a link to this section

To add an Apple Pay payment processing certificate in the Apple Developer Portal, you must first obtain a Certificate Signing Request (CSR) from Square. The Square Developer Dashboard provides a CSR file that can be submitted to Apple:

  1. Choose the application you created for your In-App Payments SDK application.

  2. Set the application to Sandbox Settings mode.

  3. Choose the Apple Pay tab.

  4. Choose Add Sandbox Certificate and follow the instructions to generate an Apple Pay certificate.

Important

If your current Apple Pay merchant ID already has an associated Apple Pay certificate, you must create a new merchant ID and then add a certificate for use with In-App Payments SDK.

Step 2: Configure your application for Apple Pay Permalink Get a link to this section

  1. Open your project in Xcode.

  2. In the Navigator Area, choose your project file, and then choose the SDK integration target in the editor area.

  3. Choose the Capabilities tab, and then enable Apple Pay by sliding the capability toggle to ON.

  4. Select the box adjacent to the merchant ID you added to trigger an automatic Xcode process that completes the three Apple Pay configuration steps.

Step 3: Set your Square application ID in your application delegate Permalink Get a link to this section

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

Step 4: Display the Apple Pay payment authorization sheet Permalink Get a link to this section

  1. Add the following extension (@implementation for Objective C) to your view controller.

  2. Paste the merchant ID associated with the Apple Pay certificate from step 1 into the PKPaymentRequest constructor to replace <#REPLACE_ME#>.

Important

Always check the SQIPInAppPaymentsSDK.canUseApplePay property of In-App Payments SDK to confirm that Apple Pay can be used before displaying the payment sheet.

@import PassKit;
@import SquareInAppPaymentsSDK;

@implementation <
#YourViewController #> - (void)requestApplePayAuthorization;
{
  if (!SQIPInAppPaymentsSDK.canUseApplePay) {
    return;
  }

  PKPaymentRequest *pmtRequest =
      [PKPaymentRequest squarePaymentRequestWithMerchantIdentifier:@"<#REPLACE_ME#>"
                                                       countryCode:@"US"
                                                      currencyCode:@"USD"];

  // Payment summary information will be displayed on the Apple Pay sheet.
  NSDecimalNumber *amount = [NSDecimalNumber decimalNumberWithString:@"1.00"];

  pmtRequest.paymentSummaryItems = @[
    [PKPaymentSummaryItem summaryItemWithLabel:@"My Company Name" amount:amount],
  ];

  PKPaymentAuthorizationViewController *pmtAuthViewController =
      [[PKPaymentAuthorizationViewController alloc] initWithPaymentRequest:pmtRequest];

  [self presentViewController:pmtAuthViewController animated:YES completion:nil];
}
@end

Step 5: Implement PKPaymentAuthorizationViewControllerDelegate methods Permalink Get a link to this section

  1. Extend your view controller by adding two delegate methods. The two delegate methods that you implement let you handle the following events:

    • didAuthorizePayment. A buyer submitted payment card information and the payment authorization sheet created a PKPpayment object. This method is invoked by the PassKit framework while the payment authorization sheet is still open.

    • didFinish. This method is invoked after the didAuthorizePayment completion handler is invoked by your code and the result is displayed to the buyer, or after the buyer cancels payment authorization.

If the buyer authorizes payment, a PKPayment object is returned and can be used in step 6 to get a Square nonce.

@import PassKit;

@interface <
#YourViewController #>() < PKPaymentAuthorizationViewControllerDelegate> @end

@implementation <
#YourViewController #>

    - (void)pmtAuthViewController : (PKPaymentAuthorizationViewController *)
          controller didAuthorizePayment : (PKPayment *)payment handler : (
              void (^)(PKPaymentAuthorizationResult *_Nonnull))completion;

{
  // TODO: Add payment->nonce logic. See Step 5: Request a Square nonce
}

- (void)pmtAuthViewControllerDidFinish:(nonnull PKPaymentAuthorizationViewController *)controller;
{ [self dismissViewControllerAnimated:YES completion:nil]; }
@end

Step 6: Request a Square nonce Permalink Get a link to this section

If the buyer authorizes payment, the PassKit framework calls your paymentAuthorizationViewController(_:didAuthorizePayment:handler:) delegate method.

  1. Create a SQIPApplePayNonceRequest object with the supplied PKPayment object to request a nonce.

  2. Call the SQIPApplePayNonceRequest. _performWithCompletionHandler method to request a nonce.

After a nonce is received, send it to your backend to charge or store the card through Square.

You can indicate a success or failure by invoking the handler provided to the paymentAuthorizationViewController(_:didAuthorizePayment:handler:) method with the appropriate parameters. This allows the Apple Pay payment sheet to display the appropriate UI to the buyer to notify them of the result.


- (void)pmtAuthViewController:(PKPaymentAuthorizationViewController *)controller
          didAuthorizePayment:(PKPayment *)payment
                      handler:(void (^)(PKPaymentAuthorizationResult *_Nonnull))completion;
{
  SQIPApplePayNonceRequest *nonceRequest =
      [[SQIPApplePayNonceRequest alloc] initWithPayment:payment];

  [nonceRequest performWithCompletionHandler:^(SQIPCardDetails *_Nullable cardDetails,
                                               NSError *_Nullable error) {
    if (error) {
      PKPaymentAuthorizationResult *errorResult =
          [[PKPaymentAuthorizationResult alloc] initWithStatus:PKPaymentAuthorizationStatusFailure
                                                        errors:@[ error ]];

      completion(errorResult);
      return;
    }

    // Send card nonce to your server to charge or store the card.
    /*
    [MyAPIClient.shared chargeCardWithNonce:cardDetails.nonce
       completion:^(id transaction, NSError *chargeError) {
        if (chargeError) {
            PKPaymentAuthorizationResult *errorResult =
                [[PKPaymentAuthorizationResult alloc]
                   initWithStatus:PKPaymentAuthorizationStatusFailure errors:@[chargeError]];

            completion(errorResult)
        } else {
            PKPaymentAuthorizationResult *successResult =
                [[PKPaymentAuthorizationResult alloc]
                   initWithStatus:PKPaymentAuthorizationStatusSuccess errors:nil];

            completion(successResult);
        }
    }];
    */

    PKPaymentAuthorizationResult *successResult =
        [[PKPaymentAuthorizationResult alloc] initWithStatus:PKPaymentAuthorizationStatusSuccess
                                                      errors:nil];

    completion(successResult);
  }];
}

Test Apple Pay and put into production Permalink Get a link to this section

To test your Apple Pay integration, you must register a valid credit card in your Apple Pay Wallet.

Important

Apple does not allow Square Sandbox test credit card values. You must use a valid credit card from your Apple Pay Wallet. The card is not charged for test payments as long as you are testing in the Square Sandbox.

Testing your Apple Pay integration involves the following steps:

  1. Choose the Apple Pay button and complete the payment sheet that opens.

  2. Verify that you are receiving a nonce in the didObtainCardDetails callback.

The nonce generated for Apple Pay can be used to take a payment with the Payments API in the Square Sandbox environment.

Production configuration Permalink Get a link to this section

When your application is ready for production, do the following:

  1. Register a production certificate for Apple Pay in iOS:

    1. Open the Developer Dashboard.

    2. Choose the application associated with your In-App Payments SDK implementation.

    3. Set the Developer Dashboard to Production Settings mode.

    4. Choose the Apple Pay tab for the selected application.

    5. Create a new Apple Pay merchant ID to be used in the next step.

    6. Choose Add Certificate under iOS and follow the onscreen instructions.

  2. Replace the Sandbox application ID in your application with the production application ID.

  3. Replace the Sandbox merchant ID set in step 4 with the new production merchant ID.