Integration

We offer this payment methods for the following integration modes. Learn in our dedicated guides about their individual differences:

• Hosted Checkout Page
• Mobile and browser SDKs

Find a high level overview in the "Process flows" chapter

Depending on the integration mode, differences apply:

• Hosted Checkout Page
• Mobile and browser SDKs

Hosted Checkout Page

Choose this minimum-effort solution to offer Apple Pay as a selectable payment method on our Hosted Checkout Page. Your customers can use this payment method if they

• make the payment from one of the supported regions
• own at least one of the supported cards in their Apple Pay wallet: Visa / MasterCard
• browse with Safari
• use one of the following devices:
  
  

  Device
  iPhones with Face ID and/or Touch ID (except iPhones 5S)
  iPad Pro, iPad Air, iPad, and iPad mini models with Touch ID or Face ID
  Apple Watch Series 1 and 2 and later, Apple Watch (1st generation)
  Mac models with Touch ID, or Mac models introduced in 2012 or later with an Apple Pay-enabled iPhone or Apple Watch

Payments going through this integration mode follow this flow:

1. Your customers finalise an order in your shop and select Apple Pay
2. You send this Hosted Checkout Page request to our platform
3. You redirect your customers to the Hosted Checkout Page where a payment sheet appears. Your customers confirm the payment
4. Our platform receives encrypted payment data from Apple Our platform decrypts the payment data and sends it to the acquirer to process the payment

To make the last step possible, you need to accept the Apple terms and conditions in the Back Office. Thus, Offering offering Apple Pay requires you to

• A) Set up your Back Office
• B) Send a specific HostedCheckout request

A) Set up your Back Office

Perform the following steps to set up Apple Pay in your PSPID:

1. Log in to the Back Office. Go to Configuration > Payment Methods > Apple Pay > Hosted Checkout registration
2. Read the Apple Pay terms & conditions by clicking on the respective link. Click on "REGISTER" to approve them. This is a requirement to authorise our platform for encrypting/decrypting sensitive data during the payment process
3. Click on "CHECK ACCOUNT STATUS" and wait for the message "Your PSPID is correctly registered" to appear. This will take only a couple of seconds: You are ready to offer Apple Pay to your customers via a specific HostedCheckout request
   
   
   The image above shows how to register and check the account's status in the Back Office. 
   
   
   • You can repeate step 3) everytime to check on your status
   • You can revoke your approval any time by clicking on "UNSUBSCRIBE"
   • If you reject the Apple Pay terms & conditions, the payment method will not be available on our Hosted Checkout Page
   • Note that Apple terms&conditions can evolve over time! Keep yourself up to date by accessing them regularly

B) Send HostedCheckout request

-Process Apple Pay transactions via Hosted Checkout Page. A standard request for this payment method looks like this:

{
   "order":{
      "amountOfMoney":{
         "currencyCode":"EUR",
         "amount":1000
      }
   },
   "hostedCheckoutSpecificInput":{
      "locale":"en_GB",
      "returnUrl":"https://www.yourwebsite.com"
   },
   "mobilePaymentMethodSpecificInput":{
      "authorizationMode":"FINAL_AUTHORIZATION",
      "paymentProductId":302
   }
}

Mobile and browser SDKs

Worldline currently supports in-app Apple Pay payments which allows you to integrate Apple Pay in your native iOS apps easily.

• The integration tutorial below focuses on the parts of the integration where our iOS SDK or one of the server SDKs is involved. Please refer to the official Apple Pay integration tutorial for all other standard parts of the integration.
• Before you add an Apple Pay button to your app it’s good to take a look at the Apple Pay human interface guidelines. Besides explaining the do’s and don’ts concerning Apple Pay, it also shows the types of buttons that Apple supports and explains how to optimize for conversion.
• Since Apple Pay uses a tokenized version of the customer’s card (called the DPAN) no sensitive card details are transferred at any point during an Apple Pay payment.

We handle decryption. This integration method allows you to keep the hand on the user experience, but let us deal with the complexity of the token decryption.

Your tasks are to create an Apple certificate and to send the encrypted data to our platform

Create Apple certificate

Apple will use this certificate to encrypt and cryptographically sign the Apple Pay payments. For this you need a standard Apple developer account and a membership in the Apple iOS developer program. Since you are creating iOS apps you will most likely already have these. If not, you can create them on Apple’s developer website.

Follow these steps to create your certificate:

1. Log in to the Back Office
2. Go to Configuration > Payment method. Select Apple Pay
3. Click on “Add new certificate”. Follow the instructions on the page to
   
   • Download the certificate signing request (CSR) on that page
   • Create the Apple Pay certificate on the Apple developer portal using that CSR
   • Upload the generated certificate in the Back Office via Configuration > Payment method > Apple Pay > Add New Certificate > Browse... > UPLOAD CERTIFICATE

Create Apple certificate

Once you have received the encrypted data back from Apple, pass them through the mobilePaymentMethodSpecificInput.encryptedPaymentdata:

{
"mobilePaymentMethodSpecificInput": {
"encryptedPaymentData": { "XXXXXXXXXXXX" },
"paymentProductId": 302,
"authorizationMode": "FINAL_AUTHORIZATION"
},
"order": {
"amountOfMoney": {
"amount": 3000,
"currencyCode": "EUR" }
}
}

You handle decryption. This integration method requires you to do more work, like decrypting the Apple Pay payment token, generating of public keys and creating certificate signing requests.
This integration method is only preferable if you want to do all the Apple Pay decryption yourself instead of having us do all of it. Another reason would be that you’d like to see inside the payment token before you let us handle the payment. Please be aware of the PCI level which applies to this way of handling Apple Pay transactions. ApplePay completely follow the EMV® Payment Tokenisation Specification – Technical Framework v1.0, the payment tokens are not considered by the PCI-SSC to be account data, therefore if you only perform Apple Pay transactions you are for this payment product eligible to complete a SAQ A. If you process other payment products as well or use our JavaScript SDK another level of SAQ can apply.

Setting up your Worldline account

First make sure Apple Pay is enabled for your account. 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.

In this scenario you need to create a certificate, but since you do all decryption you need to store the certificate yourself.

Setting up your Apple Pay environment and account

In order to enable Apple Pay on your payment page, you will need to set-up your Apple Developer account. This account will allow you to manage the certificates needed to handle the Apple Pay tokens.

Write the code for your app

When using this integration method our SDKs are involved in only two parts.

1. Adding of the Apple Pay button to your app. Clicking this button will open the Apple Pay payment sheet. See Apple tutorial "Support Apple Pay on your website with JavaScript-based APIs"
2. Sending the payment data to our API using one of our server SDKs.

Adding an Apple Pay button to your app using our iOS SDK

After the Apple Pay payment successfully finished you can get a PKPayment object that contains all order and payment information. You can simply send the data in this object to your server for decryption. The Apple Pay Tutorial contains more information on how decryption works. Notice that with this integration method the SDK is not used to wrap all the payment data in an encrypted blob, because you will not be able to decrypt this on your server.

Sending the payment data to our API using one of our server SDKs

After you decrypt the payment token on your server you need to send the data to us via one of our Server SDKs. Since you did not have our iOS SDK create an encrypted blob in this integration method you cannot provide that to us. Instead you’ll need to provide the data that’s inside the Apple Pay payment token via the mobilePaymentMethodSpecificInput object in the CreatePayment call. The table below shows you how the payment data in the PKPayment maps to the mobilePaymentMethodSpecificInput field in the SDK. (the token prefix in the left column maps to PKPayment.token.paymentData):

Field in PKPayment	Field in createPayment SDK call
token.data.applicationPrimaryAccountNumber	mobilePaymentMethodSpecificInput.decryptedPaymentData.dpan
token.data.applicationExpirationDate	mobilePaymentMethodSpecificInput.decryptedPaymentData.expiryDate
token.data.paymentData.onlinePaymentCryptogram	mobilePaymentMethodSpecificInput.decryptedPaymentData.cryptogram
token.data.paymentData.eciIndicator	mobilePaymentMethodSpecificInput.decryptedPaymentData.eci
token.header.transactionId	mobilePaymentMethodSpecificInput.transactionId

Next this mapping you also need to provide our Apple Pay payment product id (302) to the mobilePaymentMethodSpecificInput.paymentProductId field, so we can distinguish Apple Pay calls from other mobile payment product calls.

We also support third integration method where we do the decryption, but you provide the Apple Pay encrypted token instead of the encrypted blob. The Apple Pay token (PKPayment.token.paymentData) would then need to be provided via the mobilePaymentMethodSpecificInput.encryptedPaymentData field.

Besides providing these payment details fields you should also provide the order information. Please refer to “Sending the payment data to our API using one of our server SDKs” for more information on how the order fields in the PKPayment map to the fields in the Order object of the createPayment call.

Sending the payment data to our API using one of our server SDKs

After this final encryption step the encryptedFields variable of the preparedPaymentRequest contains all the sensitive payment data as a nicely encrypted String. Just as with any other payment product you should send the encryptedFields value to your own server and then use one of our server SDKs to do a createPayment call where you put the encryptedFields value in the encryptedCustomerInput field.

As with any payment we also offer you the possibility to provide order information when doing a createPayment call. Normally you decide which of the fields in your checkout process map to which field inside the Order object of the createPayment call. In the Apple Pay case however many of these fields are also available inside the PKPayment object, so we can help you with mapping them. Our iOS SDK does not offer a way to do this programmatically, but below you’ll find our preferred mapping from the PKPayment object to our Order object. Not all PKPayment fields are mapped, since we do not provide fields in all cases, but the most important ones are there. Of course you’ll have to first send this data to your server, but that’s something that you’ll most likely do anyway.