Apple Pay

Payment experience

1. 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..

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

1. 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.

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

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:

• 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
   
   

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):

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.

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
• Server-to-server (in-app payment)

Hosted Checkout Page

1. Your customers finalise an order in your shop and select Apple Pay
2. You send this Hosted Checkout Page 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
5. Our platform decrypts the payment data and sends it to the acquirer to process the payment
6. Our platform receives the transaction result
7. We redirect your customer to your ReturnUrl
8. You request the transaction result from our platform via GetPayment or receive the result via webhooks
9. 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

1. Your customers finalise an order in your shop and select Apple Pay
2. Your app sends the order request to your server via your own API and opens the payment sheet
3. Your customers confirm the payment
4. You decrypt the encrypted data received from Apple and map them to properties mobilePaymentMethodSpecificInput.decryptedPaymentData, mobilePaymentMethodSpecificInput.publicKeyHash and mobilePaymentMethodSpecificInput.ephemeralKey
5. You send the data to our platform
6. Our platform sends the data to the acquirer for processing
7. Our platform receives the transaction result
8. You request the transaction result from our platform via GetPayment or receive the result via webhooks
9. If the transaction was successful, you can deliver the goods / services

We handle decryption

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

Testing

Refer to our Test cases for test data and detailed instructions

Additional information

1. 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.
2. 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.
3. 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.
4. Apple Pay is only supported via the iOS SDK
5. 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.
6. 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