Apple Pay

Intro
Apple Pay is Apple’s mobile payment product, which allows consumers an easy and secure way to pay for physical goods and services such as groceries, clothing, tickets and reservations in your iOS apps. By using Touch ID, users can quickly and securely provide their payment.
The consumer adds her/his credit or debit cards to their wallet on their iPhone and adds the payment and shipping information to the Apple Pay wallet. The payment details the consumer enters in the Apple Pay wallet are tokenized and then securely stored. If the consumer clicks the “Buy with Apple Pay” button in the app, the payment can immediately start, since the card with which the consumers wants to pay will be loaded from the Apple Pay wallet.
Our iOS SDK allows you to easily add Apple Pay to your mobile app. We will manage the decryption of the payment data for you. If you want to, you can also choose to decrypt the data yourself and send it over to us to process the payment.
Your customers can use cards from the following brands
- Apple Pay - Visa
- Apple Pay - MasterCard
- Apple Pay - American Express
Key benefits
- A frictionless consumer experience using Apple’s native Touch ID
- Easy integration for developers using our iOS SDK
- A secure way of paying as the card data of the consumer is tokenized and the Device PAN (DPAN) is used to process the payment.
- Increase your conversion for in-app payments
- Huge potential in terms of usage, due to the millions of users on iOS devices.
Payment experience
- In countries in which Apple Pay is supported, the option to add a card to the wallet on the device of the consumer will be enabled. The consumer can add her/his payment details as well as shipping and billing address in the app..

- Within an app that supports Apple Pay, the button “Buy with Apple Pay” will appear when the consumer is ready to checkout.

- The card details of the consumer are visible and can be changed upon wish of the consumer. Next to that the total amount is also displayed. The consumer will need to use Touch ID to validate the payment.

- Once the payment is validated it will be sent via the typical purchase flow, so that we can process this payment.

Boarding
You will need a Developer Account with Apple, as well as a membership in the iOS Developer Program of Apple. Through this account you can obtain your Apple Merchant ID and you can generate your key to decrypt the payment details (either by yourself or us).
Next to that you will need to sign a “Card Not Present” agreement to process card payments in case you have not done that yet.
Countries & currencies
Supported countries
-
Australia
-
Belgium
-
Brazil
-
Bulgaria
-
Canada
-
China
-
Croatia
-
Cyprus
-
Czech Republic
-
Denmark
-
Estonia
-
Finland
-
France
-
Germany
-
Guernsey
-
Heard Island and McDonald Islands
-
Hong Kong
-
Ireland
-
Isle of Man
-
Italy
-
Japan
-
Jersey
-
Kazakhstan
-
Latvia
-
Liechtenstein
-
Lithuania
-
Malta
-
Monaco
-
Netherlands
-
New Zealand
-
Norway
-
Poland
-
Portugal
-
Romania
-
Russia
-
San Marino
-
Singapore
-
Slovakia
-
Slovenia
-
Spain
-
Sweden
-
Switzerland
-
Taiwan
-
Ukraine
-
United Arab Emirates
-
United Kingdom
-
United States Minor Outlying Islands
-
United States
-
Vatican City
Supported currencies
- Albanian lek (ALL)
- Algerian dinar (DZD)
- Angolan kwanza (AOA)
- Argentine peso (ARS)
- Armenian dram (AMD)
- Aruban florin (AWG)
- Australian dollar (AUD)
- Azerbaijani manat (AZN)
- Bahamian dollar (BSD)
- Bahraini dinar (BHD)
- Bangladeshi taka (BDT)
- Barbados dollar (BBD)
- Belarusian ruble (BYN)
- Belize dollar (BZD)
- Bermudian dollar (BMD)
- Bhutanese ngultrum (BTN)
- Boliviano (BOB)
- Bosnia and Herzegovina convertible mark (BAM)
- Botswana pula (BWP)
- Brazilian real (BRL)
- Brunei dollar (BND)
- Bulgarian lev (BGN)
- Burundian franc (BIF)
- Cambodian riel (KHR)
- Canadian dollar (CAD)
- Cape Verde escudo (CVE)
- Cayman Islands dollar (KYD)
- CFA franc BCEAO (XOF)
- CFA franc BEAC (XAF)
- CFP franc (franc Pacifique) (XPF)
- Chilean peso (CLP)
- Chinese yuan (CNY)
- Colombian peso (COP)
- Comoro franc (KMF)
- Congolese franc (CDF)
- Costa Rican colon (CRC)
- Croatian kuna (HRK)
- Czech koruna (CZK)
- Danish krone (DKK)
- Djiboutian franc (DJF)
- Dominican peso (DOP)
- East Caribbean dollar (XCD)
- Egyptian pound (EGP)
- Eritrean nakfa (ERN)
- Ethiopian birr (ETB)
- Euro (EUR)
- Falkland Islands pound (FKP)
- Fiji dollar (FJD)
- Gambian dalasi (GMD)
- Georgian lari (GEL)
- Ghanaian cedi (GHS)
- Gibraltar pound (GIP)
- Guatemalan quetzal (GTQ)
- Guinean franc (GNF)
- Guyanese dollar (GYD)
- Haitian gourde (HTG)
- Honduran lempira (HNL)
- Hong Kong dollar (HKD)
- Hungarian forint (HUF)
- Icelandic króna (ISK)
- Indian rupee (INR)
- Indonesian rupiah (IDR)
- Iraqi dinar (IQD)
- Israeli new shekel (ILS)
- Jamaican dollar (JMD)
- Japanese yen (JPY)
- Jordanian dinar (JOD)
- Kazakhstani tenge (KZT)
- Kenyan shilling (KES)
- Kuwaiti dinar (KWD)
- Kyrgyzstani som (KGS)
- Lao kip (LAK)
- Lebanese pound (LBP)
- Lesotho loti (LSL)
- Liberian dollar (LRD)
- Libyan dinar (LYD)
- Macanese pataca (MOP)
- Macedonian denar (MKD)
- Malagasy ariary (MGA)
- Malawian kwacha (MWK)
- Malaysian ringgit (MYR)
- Maldivian rufiyaa (MVR)
- Mauritanian ouguiya (MRO)
- Mauritian rupee (MUR)
- Mexican peso (MXN)
- Moldovan leu (MDL)
- Mongolian tugrik (MNT)
- Moroccan dirham (MAD)
- Mozambican metical (MZN)
- Myanmar kyat (MMK)
- Namibian dollar (NAD)
- Nepalese rupee (NPR)
- Netherlands Antillean guilder (ANG)
- New Taiwan dollar (TWD)
- New Zealand dollar (NZD)
- Nicaraguan córdoba (NIO)
- Nigerian naira (NGN)
- Norwegian krone (NOK)
- Omani rial (OMR)
- Pakistani rupee (PKR)
- Panamanian balboa (PAB)
- Papua New Guinean kina (PGK)
- Paraguayan guaraní (PYG)
- Peruvian nuevo sol (PEN)
- Philippine peso (PHP)
- Polish zloty (PLN)
- Pound sterling (GBP)
- Qatari riyal (QAR)
- Romanian new leu (RON)
- Russian ruble (RUB)
- Rwandan franc (RWF)
- Saint Helena pound (SHP)
- Salvadoran Colon (SVC)
- Samoan tala (WST)
- São Tomé and Príncipe dobra (STD)
- Saudi riyal (SAR)
- Serbian dinar (RSD)
- Seychelles rupee (SCR)
- Sierra Leonean leone (SLL)
- Singapore dollar (SGD)
- Solomon Islands dollar (SBD)
- Somali shilling (SOS)
- South African rand (ZAR)
- South Korean won (KRW)
- Sri Lankan rupee (LKR)
- Surinamese dollar (SRD)
- Swazi lilangeni (SZL)
- Swedish krona/kronor (SEK)
- Swiss franc (CHF)
- Tajikistani somoni (TJS)
- Tanzanian shilling (TZS)
- Thai baht (THB)
- Tongan paʻanga (TOP)
- Trinidad and Tobago dollar (TTD)
- Tunisian dinar (TND)
- Turkish lira (TRY)
- Turkmenistani manat (TMT)
- Ugandan shilling (UGX)
- Ukrainian hryvnia (UAH)
- United Arab Emirates dirham (AED)
- United States dollar (USD)
- Uruguayan peso (UYU)
- Uzbekistan som (UZS)
- Vanuatu vatu (VUV)
- Venezuelan bolívar (VEF)
- Vietnamese dong (VND)
- Yemeni rial (YER)
- Zambian kwacha (ZMW)
- Zimbabwe dollar (ZWD)
Integration
We offer this payment methods for the following integration modes. Learn in our dedicated guides about their individual differences:
Find a high level overview in the "Process flows" chapter
Depending on the integration mode, differences apply:
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:
- Your customers finalise an order in your shop and select Apple Pay
- You send this Hosted Checkout Page request to our platform
- You redirect your customers to the Hosted Checkout Page where a payment sheet appears. Your customers confirm the payment
- 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
Perform the following steps to set up Apple Pay in your PSPID:
- Log in to the Back Office. Go to Configuration > Payment Methods > Apple Pay > Hosted Checkout registration
- 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
- 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

- 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:
- Log in to the Back Office
- Go to Configuration > Payment method. Select Apple Pay
- 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

- Make sure to create separate certificate for both our test and production environment
- Apple will only allow you to create a maximum of three Apple Pay certificates per Apple merchant id. Apple allows you to have more than one so you can migrate to a new certificate when the old one is about to expire. Keep in mind that only one of the certificates per Apple merchant id can be active at any given time. You can activate or deactivate a certificate on the Apple Developer portal
- Due to the limited number of of certificates per Apple merchant id available, we recommend using separate Apple merchant id for both test and production environment
- Apple certificates expire after two years. Make sure to upload a new one in the Back Office in time. We will send you an email a few weeks before your certificate expires to remind you to create a new one
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.
- 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"
- 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.
createPayment’s Order object field |
PKPayment field |
order.customer.contactDetails.emailAddress |
billingContact.emailAddress or if that is not available: shippingContact.emailAddress |
order.customer.contactDetails.phoneNumber |
billingContact.phoneNumber or if that is not available: shippingContact.phoneNumber |
order.customer.personalInformation.name.surname |
billingContact.name.familyName |
order.customer.personalInformation.name.firstName |
billingContact.name.givenName |
order.customer.personalInformation.name.title |
billingContact.name.namePrefix |
order.customer.billingAddress.street |
billingContact.postalAddress.street |
order.customer.billingAddress.city |
billingContact.postalAddress.city |
order.customer.billingAddress.state |
billingContact.postalAddress.state |
order.customer.billingAddress.zip |
billingContact.postalAddress.postalCode |
order.customer.billingAddress.countryCode |
billingContact.postalAddress.isoCountryCode |
order.customer.shippingAddress.name.surname |
shippingContact.name.familyName |
order.customer.shippingAddress.name.firstName |
shippingContact.name.givenName |
order.customer.shippingAddress.name.title |
shippingContact.name.namePrefix |
order.customer.shippingAddress.street |
shippingContact.postalAddress.street |
order.customer.shippingAddress.city |
shippingContact.postalAddress.city |
order.customer.shippingAddress.state |
shippingContact.postalAddress.state |
order.customer.shippingAddress.zip |
shippingContact.postalAddress.postalCode |
order.customer.shippingAddress.countryCode |
shippingContact.postalAddress.isoCountryCode |
Example of minimal Apple Pay Create Payment request
{
"mobilePaymentMethodSpecificInput": {
"decryptedPaymentData": {
"dpan": "4761120010000492",
"cryptogram": "jiSRYgf6G2rjYwAAC0GPAHQAAAA=",
"expiryDate": "1225",
"cardholderName": "John Doe",
"eci": "7"
},
"paymentProductId": 302,
"authorizationMode": "FINAL_AUTHORIZATION"
},
"order": {
"amountOfMoney": {
"amount": 3000,
"currencyCode": "EUR"
}
}
}
Process flows
You can process transactions via both integration modes Hosted Checkout Page and Server-to-server. As there are some differences in the flow, we describe them separately. Read our dedicated paragraphs in the "Integration" chapter to get detailed information about each mode
Hosted Checkout Page
- Your customers finalise an order in your shop and select Apple Pay
- You send this Hosted Checkout Page to our platform
- You redirect your customers to the Hosted Checkout Page where a payment sheet appears. Your customers confirm the payment
- Our platform receives encrypted payment data from Apple
- Our platform decrypts the payment data and sends it to the acquirer to process the payment
- Our platform receives the transaction result
- We redirect your customer to your ReturnUrl
- You request the transaction result from our platform via GetPayment or receive the result via webhooks
- If the transaction was successful, you can deliver the goods / services

Server-to-server (in-app payment)
Our platform allows you to handle the decryption of sensitive data yourself or leave this to us. As there are differences in the flow, we describe them seperately:
You handle decryption
- Your customers finalise an order in your shop and select Apple Pay
- Your app sends the order request to your server via your own API and opens the payment sheet
- Your customers confirm the payment
- You decrypt the encrypted data received from Apple and map them to properties mobilePaymentMethodSpecificInput.decryptedPaymentData, mobilePaymentMethodSpecificInput.publicKeyHash and mobilePaymentMethodSpecificInput.ephemeralKey
- You send the data to our platform
- Our platform sends the data to the acquirer for processing
- Our platform receives the transaction result
- You request the transaction result from our platform via GetPayment or receive the result via webhooks
- If the transaction was successful, you can deliver the goods / services

We handle decryption
- Your customers finalise an order in your shop and select Apple Pay
- Your app sends the order request to your server via your own API and opens the payment sheet
- Your customers confirm the payment
- You send the encrypted payment data in property mobilePaymentMethodSpecificInput. encryptedPaymentdata to our platform via the Server API
- Our platform decrypts the payment data and sends them to Apple
- Our platform receives encrypted payment data from Apple
- Our platform decrypts the payment data and sends it to the acquirer to process the payment
- Our platform receives the transaction result
- You request the transaction result from our platform via GetPayment or receive the result via webhooks
- If the transaction was successful, you can deliver the goods / services

Testing
Refer to our Test cases for test data and detailed instructions
Make sure to use the right endpoint and switch back to the live URL as soon as you have finished your tests
Additional information
- Please note that Apple Pay only works on relatively newer consumer devices, so as of iPhone 6 and up as well as of iPad mini 3, iPad Pro 9,7 and iPad Air 2 and up. Apple does provide information on their website with regards to which devices do support Apple Pay.
- You can only use Worldline to offer the purchase of physical goods or services(like taxi services, clothing, airline tickets) via Apple Pay, as described on Apple’s website. Purchases for digital goods (such as in-game items, app content or subscription services) should use In-App purchase as the method of payment.
- On your invoice the transactions for Apple Pay will be aggregated under the card scheme your consumer used. So if a consumer paid using a MasterCard from their Apple Wallet, you will see the transaction being counted under MasterCard.
- Apple Pay is only supported via the iOS SDK
- Once a consumer has added her/his debit and/or credit card to the Apple Pay app, it will be tokenized and get a Device PAN (DPAN) which will be used for payments.
- At the moment we support the following networks through Apple Pay:
Visa
MasterCard
Assets
The Apple Pay identity guidelines are described on the website of Apple. You can also find the assets on your Apple developer account.
Refunds
Apple Pay card payments can be refunded upon requested to the card used to make the original transaction. The request can be made through the payment console or via an API call. It is also possible for a transaction whilst in the process of being refunded to still be reversed and a chargeback made by the Consumer. The issuing bank will only accept the claim in cases where the refund hasn’t been fully processed.
Refunds can only be accepted if:
- the original transaction was collected through us
- The refund value does not exceed 100% of the value of the original transaction.
- The merchant category code is not 7995 (Betting (including Lottery Tickets), Casino Gaming Chips, Off-Track Betting and Wagers). 7995 refunds can only be made via a bank transfer or, for payouts merchants can request a CFT/OCT account.
A few general rules apply:
- We may reject refund requests if the value of the refund exceeds 100% of the value of the collected transactions.
- Refunds have to be accompanied with the original transaction reference number.
Partial refunds
When a partial refund needs to be applied, the lower amount can be send within the API-call or through the payment console. Partial refunds are often used when multiple products/services are bought by the consumer and one of the products or services is returned.
- Recurring payments are not supported
- Payouts are not supported
- AVS and 3D Secure are not needed