Enable Apple Pay

Applies to: In-App Payments SDK - iOS

Learn how to enable Apple Pay for the Square In-App Payments SDK.

Overview

Use the following step-by-step instructions to integrate Apple Pay with the In-App Payments SDK on an iOS device. It also shows how to integrate and test the Apple Pay digital wallet in the Square Sandbox and how to move the integration into production.

Link to section

Requirements and limitations

You're a US, Canadian, UK, or AU Square seller. Apple Pay for the In-App Payments SDK is only available for Square sellers based in the United States, Canada, the United Kingdom, or Australia.
You've followed the instructions in Build on iOS. This topic doesn't cover the general setup of the In-App Payments SDK.
You've added your Apple developer account to Xcode.
The deployment target for your application is iOS 10.0 or later.

Link to section

1. Upload an Apple Pay certificate to the Developer Console

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 Console provides a CSR file that can be submitted to Apple:

Choose the application you created for your In-App Payments SDK application.
At the top of the page, choose Sandbox mode.
In the left pane, choose Apple Pay.
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 the In-App Payments SDK.

A single In-App Payments SDK application associated with a Payment Processing Certificate and Apple Pay merchant ID might be listed multiple times in the Apple Store.

Link to section

2. Configure your application for Apple Pay

Open your project in Xcode.
In the Navigator Area, choose your project file, and then choose the SDK integration target in the editor area.
Choose the Capabilities tab, and then enable Apple Pay by sliding the capability toggle to ON.
Select the box adjacent to the merchant ID you added to trigger an automatic Xcode process that completes the three Apple Pay configuration steps.

Link to section

3. Set your application ID in your application delegate

Update REPLACE_ME in the following code with your Square application ID. If you don't 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 Console to Sandbox mode before completing the following instructions in this step.

import SquareInAppPaymentsSDK

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_: UIApplication,
                     didFinishLaunchingWithOptions _:
                     [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        // Set your Square Application ID
        SQIPInAppPaymentsSDK.squareApplicationID = "<# REPLACE_ME #>"
        return true
    }
}

Replace <# REPLACE_ME #> with your application ID. For example, the application ID sq0ids-KHbh5gEaJuH7GEi1lgGMBQ replaces the placeholder as shown in the following code:

SQIPInAppPaymentsSDK.squareApplicationID = "sq0ids-KHbh5gEaJuH7GEi1lgGMBQ"

Link to section

4. Display the Apple Pay payment authorization sheet

Add the following extension (@implementation for Objective C) to your view controller.
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 the In-App Payments SDK to confirm that Apple Pay can be used before displaying the payment sheet.

import PassKit
import SquareInAppPaymentsSDK

extension<#YourViewController#> {
    func requestApplePayAuthorization() {
        guard SQIPInAppPaymentsSDK.canUseApplePay else {
            return
        }
        let paymentRequest = PKPaymentRequest.squarePaymentRequest(
            // Set to your Apple merchant ID
            merchantIdentifier: <#REPLACE_ME#>,
            countryCode: "US",
            currencyCode: "USD"
        )

        // Payment summary information will be displayed on the Apple Pay sheet.
        paymentRequest.paymentSummaryItems = [
            PKPaymentSummaryItem(label: "Testing Apple Pay", amount: 1.00),
        ]

        let paymentAuthorizationViewController =
            PKPaymentAuthorizationViewController(paymentRequest: paymentRequest)

        paymentAuthorizationViewController!.delegate = self

        present(paymentAuthorizationViewController!, animated: true, completion: nil)
    }
}

Link to section

5. Implement PKPaymentAuthorizationViewControllerDelegate methods

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 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 payment token.

import PassKit

extension<#YourViewController#>: PKPaymentAuthorizationViewControllerDelegate {
    func paymentAuthorizationViewController(
        _: PKPaymentAuthorizationViewController,
        didAuthorizePayment _: PKPayment,
        handler _: @escaping (
            PKPaymentAuthorizationResult) -> Void
    ) {
        // TODO: Add payment->nonce exchange logic. See Step 5: Request a Square
        // nonce
    }

    func paymentAuthorizationViewControllerDidFinish(
        _: PKPaymentAuthorizationViewController
    ) {
        dismiss(animated: true, completion: nil)
    }
}

Link to section

6. Request a Square payment token

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

Create a SQIPApplePayNonceRequest object with the supplied PKPayment object to request a payment token.
Call the SQIPApplePayNonceRequest performWithCompletionHandler method to request a payment token.

After a payment token 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.

func paymentAuthorizationViewController(
    _: PKPaymentAuthorizationViewController,
    didAuthorizePayment payment: PKPayment,
    handler completion: @escaping (
        PKPaymentAuthorizationResult) -> Void
) {
    // Exchange the authorized PKPayment for a nonce.
    let nonceRequest = SQIPApplePayNonceRequest(payment: payment)
    nonceRequest.perform { cardDetails, error in
        if let cardDetails = cardDetails {
            // Send the card nonce to your server to charge the card or store
            // the card on file.

            /*
             MyAPIClient.shared.chargeCard(withNonce: cardDetails.nonce) {
                 transaction, chargeEerror in

                 if let chargeError = chargeError {
                     completion(PKPaymentAuthorizationResult(status: .failure,
                     errors: [chargeError]))
                 }
                 else {
                     completion(PKPaymentAuthorizationResult(status: .success,
                     errors: nil))
                 }
             }
             */

            completion(PKPaymentAuthorizationResult(status: .success, errors: nil))
        } else if let error = error {
            print(error)
            completion(PKPaymentAuthorizationResult(status: .failure, errors: [error]))
        }
    }
}

Link to section

Test Apple Pay and put into production

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

Important

Apple doesn't allow Square Sandbox test credit card values. You must use a valid credit card from your Apple Pay wallet. The card isn't charged for test payments as long as you're testing in the Square Sandbox.

Testing your Apple Pay integration involves the following steps:

Choose the Apple Pay button and complete the payment sheet that opens.
Verify that you're receiving a payment token in the didObtainCardDetails callback.

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

Link to section

Production configuration

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

Register a production certificate for Apple Pay in iOS:
1. Open the Developer Console.
2. Choose the application associated with your In-App Payments SDK implementation.
3. Set the Developer Console to Production mode.
4. In the left pane, choose Apple Pay 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 instructions.
Replace the Sandbox application ID in your application with the production application ID.
Replace the Sandbox merchant ID set in step 4 with the new production merchant ID.

Overview Requirements and limitations 1. Upload an Apple Pay certificate to the Developer Console 2. Configure your application for Apple Pay 3. Set your application ID in your application delegate 4. Display the Apple Pay payment authorization sheet 5. Implement PKPaymentAuthorizationViewControllerDelegate methods 6. Request a Square payment token Test Apple Pay and put into production

If you need more assistance, contact Developer and App Marketplace Support or ask for help in the Developer Forums.

Docs

Enable Apple Pay

Swift

Objective C

On this page

Overview

Requirements and limitations

1. Upload an Apple Pay certificate to the Developer Console

Important

2. Configure your application for Apple Pay

3. Set your application ID in your application delegate

Important

4. Display the Apple Pay payment authorization sheet

Important

5. Implement PKPaymentAuthorizationViewControllerDelegate methods

6. Request a Square payment token

Test Apple Pay and put into production

Important

Production configuration

On this page