Apple Pay for Apps: decryption is done by you

In order to set up Apple Pay in your native iOS app follow the instructions on this page. This page describes setting up in-app payments where the Apple Pay payment tokens will be decrypted in your systems. Please note that when you decrypt the payment tokens in your systems, they will have to adhere to the PCI SAQ-D requirements. Before you decide to decrypt the tokens yourself, we strongly advise you to investigate whether having Worldline handle the decryption of the payment tokens is not an option for you.

You need to take care of the following steps:

• Enable Apple Pay at Worldline
• Create an Apple Developer account and set up the relevant configuration
• Implement Apple Pay in your app
• Decrypt the payment token in your systems
• Send the decrypted payment details via the Create Payment API

Enabling Apple Pay at Worldline

First make sure Apple Pay is enabled for your account (merchant ID). To do so contact your account manager at Worldline who will work together with your implementation manager. They will be able to set the product up for you.

Create an Apple developer account

If you do not have one yet, make sure to set up an Apple Developer account. Have a look at the following page for instructions and more information about organisational Developer accounts.

Configuring Apple Pay in app

In order to start accepting Apple Pay payments in your app, some configuration needs to be in place. Apple Pay requires setting up a payment processing certificate to protect your customers payment details. The certificate is used to encrypt their payment details, which creates the Apple Pay payment token. This token can be securely sent from your app to your server. The private part of the certificate will be used to decrypt the token to finish the payment.

If you choose this to decrypt the payment tokens in your own system you’ll be setting up your merchant ID, Apple Pay payment processing certificate, merchant certificate and verified domains with Apple. No configuration with Worldline is required.  Please consult the Apple Pay Setup section in Apple’s documentation to set this up.

Please note that this option requires you to implement the decryption of the Apple Pay payment token on your own systems, which also means you need to adhere to the PCI requirements to be able to process this payment data. Once the token is decrypted, the payment details can be sent via the Create Payment API.

Implement Apple Pay in your app

Next you can start with the technical integration. Our SDKs and APIs provide all the data you need, in the correct format that can be immediately provided to Apple. Follow the steps below to learn how to get the data, and to integrate Appie Pay in your app.

1. Retrieve Apple Pay via the payment product(s) API

As with Apple Pay on the web, Apple Pay may not always be available to your customer. The iOS Client SDKs make it easy for you to know whether Apple Pay is available by simply hiding the Apple Pay payment product from the get Payment Product(s) responses. So if Apple Pay is not available for the current payment, it will not be returned. Availability of Apple Pay depends on a couple of things:

1. The iOS version of the consumer’s device.
2. If the user has configured Apple Pay.
3. The iOS settings like parental control, if the device is rooted, etc.
4. If you accept any of the cards that were added to Apple Pay.
5. If at least one of these cards can be used for the current payment, depending on the limitations that have been set up while boarding with us, such as minimal amount, country, and currencies.

func getApplePayPaymentProduct() {
    // session is an already initialized instance of the SDK's Session object
    session.paymentProduct(withId: "302", context: paymentContext, success: {
        // Apple Pay is available, render the Apple Pay button
    },
    failure: {
        // Apple Pay is not available
    })
}

2. Strong Customer Authentication (SCA) compliance

In case you use an acquirer that is based in one of the European Economic Area (EEA) countries, you need to make sure that you provide information about the country of the acquirer when initializing Apple Pay, to be compliant with the PSD2 Strong Customer Authentication (SCA) requirements. The correct Acquirer Country is available in the payment product object: acquirerCountry. Apple Pay will return the appropriate credentials for transactions based on the country of the acquirer used for this transaction.

More information on Strong Customer Authentication compliance for Apple Pay can be found on Apple's pages.

The next step is to initialize an instance of span PKPaymentRequest. Below is a minimal example on creating a PKPaymentRequest and how to obtain and provide fields like the acquirerCountry and supportedNetworks. Please see Apple's documentation for more details on initializing Apple Pay.

func initializePaymentRequest(with product: paymentProduct) -> PKPaymentRequest {
    // paymentProduct is the Apple Pay product that was retrieved in the previous step

    let paymentRequest = PKPaymentRequest()

    // The acquirer country is required for SCA in the EEA.
    paymentRequest.countryCode = paymentProduct.acquirerCountry
    if let supportedNetworks = paymentProduct.paymentProduct302SpecificData?.paymentProductNetworks {
        paymentRequest.supportedNetworks = supportedNetworks
    }

    // context is an instance of PaymentContext
    paymentRequest.currencyCode = context.amountOfMoney.currencyCodeString
    
    // The products that your customer is buying
    paymentRequest.paymentSummaryItems = getSummaryItems()

    // This is the merchantId that is registered in the Apple developer portal
    // It must be linked to the certificate that was set up
    paymentRequest.merchantIdentifier = merchantId

    // These capabilities indicate what security flows are supported by you.
    paymentRequest.merchantCapabilities = [.capability3DS, .capabilityEMV, .capabilityDebit, .capabilityCredit]

    return paymentRequest
}

Use this PaymentRequest object to create an instance of PKPaymentAuthorizationViewController. Please see Apple's documentation for more details on how to bring up the Apple Pay payment screen and how to interact with it.

3. Sending the payment details

After having sent the token from the app to your servers and decrypting the Apple Pay payment token, you have to use the mobilePaymentMethodSpecificInput.decryptedPaymentData field in the Create Payment API to provide the payment details. Below is an example on how you can provide the decrypted payment data in the create payment request. 

{
    "order" : {
        "amountOfMoney" : {
            "currencyCode" : "EUR",
            "amount" : 2980
        },
        "customer" : {
            "locale" : "en_US",
            "merchantCustomerId" : "1234",
            "billingAddress": {
                "countryCode": "NL"
            }
        }
    },
    "mobilePaymentMethodSpecificInput": {
        "paymentProductId": 302,
        "decryptedPaymentData": {
            "dpan": "4111111111111111",
            "expiryDate": "1220",
            "eci": 5,
            "cryptogram": "<paymentData.onlinePaymentCryptogram>"
        }
    }
}

The table below shows in more detail how the payment data in the PKPayment maps to the mobilePaymentMethodSpecificInput fields in the SDK. (the token prefix in the left column maps to PKPayment.token.paymentData):

Next to the fields in the mapping above, you also need to provide our Apple Pay payment product id (302) in the mobilePaymentMethodSpecificInput.paymentProductId field.