worldline Direct
Sign up

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
Apple Pay - Cartes Bancaires

Overview

Payment group:
Payment product id:
302
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

The image above shows the steps of Apple Pay flow.
  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..
  2. Within an app that supports Apple Pay, the button “Buy with Apple Pay” will appear when the consumer is ready to checkout.

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

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

Onboarding

To accept payments for this payment method regardless of the integration mode, make sure you have an acquisition contract with one of the supported acquirers. We will clarify this with you during the onboarding process.

Depending on the integration mode, further requirements are applicable:

  • Hosted Checkout Page: Accept Apple's terms and conditions as described in the dedicated chapter. This will allow you to register your Apple Merchant ID and to offer Apple Pay on our secure payment page.
  • Mobile/Client Integration: Get an active Apple developer account and a subscription to the iOS developer program. This will allow you to create your Apple Pay certificates as described in the dedicated chapter.

We will be happy to help you get started.

Countries & currencies

Supported countries

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

To make this payment method appear on our Hosted Checkout Page as a selectable payment method, your customers need to:

  • Be located in one of the supported countries.
  • Own at least one of the supported cards in their Apple Pay wallet:
    Apple Pay - Visa
    Apple Pay - MasterCard
    Apple Pay - American Express
    Apple Pay - Cartes Bancaires
    .
  • Browse with Safari.
  • Use one of the following devices:
    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.

Make also sure to register your Merchant ID as described in the dedicated chapter.

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

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

Depending on the integration mode, differences apply:

Hosted Checkout Page

Add the following properties to a standard CreateHostedCheckout request:

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

order.amountOfMoney
     amount
     currencyCode

amount: The gross amount you want to charge for this order.
currencyCode: The ISO 4217 currency code for this amount.

hostedCheckoutSpecificInput
    locale
    returnUrl

locale: The language version of our Hosted Checkout Page and the Apple Pay payment sheet.

returnUrl: The URL we redirect your customers to after the payment has been finalised.

mobilePaymentMethodSpecificInput
     authorizationMode
     paymentProductId

authorizationMode: Set to either "FINAL_AUTHORIZATION"/"SALE" depending on whether you want to process payments in authorisation/direct sale mode.

paymentProductId: The numeric identifier of the payment method on our platform. Find this id in the "Overview" chapter. It instructs our platform to send your customers directly to the Apple Pay payment sheet. If left out, our platform sends your customers to the Hosted Checkout Page instead, allowing them to choose this or any other payment method in your account.

Find detailed information about this object and its properties in our CreateHostedCheckoutAPI.

Mobile/Client Integration

Depending on the decryption mode, differences apply:

We handle decryption

This mode outsources the complexity of the payment data decryption to our platform. Make sure to create certificates and upload them as described in the dedicated chapter

Add the following properties to a standard CreatePayment request when sending the decrypted data to our platform:

{
    "mobilePaymentMethodSpecificInput": {
        "encryptedPaymentData": "xxx",
        "paymentProductId": 302,
        "authorizationMode": "FINAL_AUTHORIZATION",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYcF+GXB1DjbKLn5PgxVky2QTk53HjfoIXOvE7kH6+lixJKSTv1AuPlAUsBD2Nu2qHFwP50Abeh1onwvmvMYY/g==",
        "publicKeyHash": "uUhU0fJoEJNk11gR8Ptd5Uw+jAnudz24rC2EuVcrZhM="
    },
    "order": {
        "amountOfMoney": {
            "amount": 3000,
            "currencyCode": "EUR"
        }
    }
}
Properties Remarks

order.amountOfMoney
     amount
     currencyCode

amount: The gross amount you want to charge for this order.
currencyCode: The ISO 4217 currency code for this amount.

mobilePaymentMethodSpecificInput
     authorizationMode
     paymentProductId
     ephemeralKey
     publicKeyHash

authorizationMode: Set to either "FINAL_AUTHORIZATION"/"SALE" depending on whether you want to process payments in authorisation/direct sale mode.

paymentProductId: The numeric identifier of the payment method on our platform. Find this id in the "Overview" chapter.

encryptedPaymentData: The encrypted payment data which our platform decrypts for the actual transaction.

ephemeralKey: A unique key used by Apple to encrypt data.

publicKeyHash: A unique identifier to get the key used by Apple to encrypt data.

Find detailed information about this object and its properties in our CreatePaymentAPI.

You handle decryption

This mode requires you to decrypt the payment data by yourself and send it to our platform. This might have an impact on your PCI compliance type. Contact your acquirer for more information. 

You also need to write the code for this solution by yourself. However, you can use our SDKs in two instances:

  1. iOS SDK: Adding the Apple Pay button to your app that opens the Apple Pay payment sheet. Read the Apple tutorial for more information.
  2. Server SDKs: Sending the decrypted payment data to our platform.

Make sure to create the certificates and upload them on your server as described in the dedicated chapter

Add the following properties to a standard CreatePayment request when sending the decrypted data to our platform:

{
    "mobilePaymentMethodSpecificInput": {
        "decryptedPaymentData": {
            "dpan": "4761120010000492",
            "cryptogram": "jiSRYgf6G2rjYwAAC0GPAHQAAAA=",
            "expiryDate": "1225",
            "cardholderName": "John Doe",
            "eci": "7"
        },
        "paymentProductId": 302,
        "authorizationMode": "FINAL_AUTHORIZATION"
    },
    "order": {
        "amountOfMoney": {
            "amount": 3000,
            "currencyCode": "EUR"
        }
    }
}
Properties Remarks

order.amountOfMoney
     amount
     currencyCode

amount: The gross amount you want to charge for this order.
currencyCode: The ISO 4217 currency code for this amount.

mobilePaymentMethodSpecificInput
     authorizationMode
     paymentProductId
     decryptedPaymentData
          dpan
          cryptogram
          expiryDate
          cardholderName
          eci

authorizationMode: Set to either "FINAL_AUTHORIZATION"/"SALE" depending on whether you want to process payments in authorisation/direct sale mode.

paymentProductId: The numeric identifier of the payment method on our platform. Find this id in the "Overview" chapter.

decryptedPaymentData: The decrypted payment data for the actual transaction. Read the dedicated chapter for detailed information.

Map PKPayment properties to mobilePaymentMethodSpecificInput

After decrypting the payment token on your e-commerce server, you need to send this data via a CreatePayment request. As you cannot use our iOS SDK to create an encrypted blob, you need to pass this data via mobilePaymentMethodSpecificInput.decryptedPaymentData. This table shows how PKPayment maps to mobilePaymentMethodSpecificInput.decryptedPaymentData.

PKPayment object decryptedPaymentData property

token.data.applicationPrimaryAccountNumber

dpan

token.data.applicationExpirationDate

expiryDate

token.data.paymentData.onlinePaymentCryptogram

cryptogram

token.data.paymentData.eciIndicator

eci


Depending on the individual request, PKPayment may contain further order information. Apply the following mapping to include them in your CreatePayment request:

PKPayment object order.customer property

billingContact.emailAddress or shippingContact.emailAddress
billingContact.phoneNumber or shippingContact.phoneNumber

contactDetails
     emailAddress
     phoneNumber

billingContact.name
     familyName
     givenName
     namePrefix

personalInformation.name
     surname
     firstName
     title

billingContact.postalAddress
     street
     city
     state
     postalCode
     isoCountryCode

billingAddress
     street
     city
     state
     zip
     countryCode

order.customer.shippingAddress
     name
          surname
          firstName
          title
     street
     city
     state
     zip
     countryCode

shippingAddress
     name
          surname
          firstName
          title
      street
      city
      state
      zip
      countryCode

Find detailed information about this object and its properties in our CreatePaymentAPI.

Process flows

Depending on the integration mode and the decryption mode, differences apply:

Hosted Checkout Page

Make sure to register your Merchant ID as described here.

  1. Your customers finalise an order in your shop and select Apple Pay.
  2. You send this CreateHostedCheckout request to our platform.
  3. You redirect your customers via the redirectUrl to the Apple Pay payment sheet. 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 your acquirer to process the payment.
  6. We receive the transaction result.
  7. You redirect your customers to your redirectUrl.
  8. You request the transaction result from our platform via GetHostedCheckout or receive the result via webhooks.
  9. If the transaction was successful, you can deliver the goods/services.

Mobile/Client Integration

Depending on whether you leave handling payment data decryption to us or do this by yourself, differences apply:

We handle decryption

Make sure to create Apple certificates as described here.

  1. Your customers finalise an order in your app and select Apple Pay.
  2. Your app sends the order request to your e-commerce server and opens the payment sheet.
  3. Your customers confirm the payment in the app.
  4. You send the encrypted payment data in property mobilePaymentMethodSpecificInput.encryptedPaymentdata via this CreatePayment request to our platform.
  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 your acquirer to process the payment.
  8. We receive the transaction result.
  9. You request the transaction result from our platform via GetPaymentDetails or receive the result via webhooks.
  10. Your app displays the transaction result.
  11. If the transaction was successful, you can deliver the goods/services.

You handle decryption 

Make sure to create Apple certificates and configure your Worldline/Apple developer account as described here.

  1. Your customers finalise an order in your app and select Apple Pay.
  2. Your app sends the order request to your e-commerce server and opens the payment sheet.
  3. Your customers confirm the payment in the app.
  4. Your e-commerce server receives the encrypted data from Apple.
  5. Your e-commerce server decrypts the data.
  6. You send the decrypted payment data in properties
    mobilePaymentMethodSpecificInput.decryptedPaymentData
    mobilePaymentMethodSpecificInput.publicKeyHash
    mobilePaymentMethodSpecificInput.ephemeralKey
    via this CreatePayment request to our platform.
  7. Our platform sends the decrypted payment data to your acquirer to process the payment.
  8. We receive the transaction result.
  9. You request the transaction result from our platform via GetPaymentDetails or receive the result via webhooks.
  10. Your app displays the transaction result.
  11. 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

Offering this payment method requires you to either register your Merchant ID (for Hosted Checkout Page integration mode) and/or created your Apple Pay certificates (for Mobile/Client Integration)

Register Merchant ID (Hosted Checkout Page)

Follow these steps:

  1. Log in to the Back Office. Go to Configuration > Payment Methods > Apple Pay > Hosted Checkout registration.
  2. Read the Apple Pay terms and conditions by clicking on the respective link. Click on "REGISTER" to approve them.
  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 Hosted Checkout Page integration mode.

Mind the following: 

  • You can repeat step 3 anytime to check 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.
  • Apple's terms and conditions can change. Keep yourself up to date by accessing them regularly.

Create Apple Pay certificates (Mobile/Client integration)

For payments via Mobile/Client Integration, you need to create Apple certificates. Depending on whether you leave handling payment data decryption to us or do this by yourself, differences apply:

We handle decryption

This requires you to create certificates and upload them in the Back Office. To do so, follow these steps:

  1. Log in to the Back Office. Go to Configuration > Payment Methods > Apple Pay > Add new certificate.
  2. Follow the instructions on the page to
    a) Download the certificate signing request (CSR) on that page.
    b) Create the Apple Pay certificate on the Apple developer portal using that CSR.
    c) Upload the generated certificate via the Browse.../UPLOAD CERTIFICATE buttons.

Find detailed information about how to apply this decryption mode in the “Integration” and “Process flows" chapters.

Mind the following: 

  • Make sure to create separate certificates for our test / production environment.
  • Apple allows you to create a maximum of three certificates per Merchant ID. Mind that only one certificate per Merchant ID can be active. Use the three slots to manage expiring certificates.
  • Due to this limitation, we recommend using different Merchant ID for our test / production environment.
  • Apple certificates expire after two years. Make sure to timely create and upload a new one. We will notify you via e-mail as soon as a certificate is about to expire.

You handle decryption

This requires you to create certificates and upload them on your server. To do so, follow these steps:

  1. Contact us to set up your Worldline account to allow handling decryption by yourself.
  2. Set up your Apple Developer account to allow handling Apple Pay token by yourself.
  3. Create the Apple Pay certificates on the Apple developer portal
    a) Create a Certificate signing request
    b) Create a Merchant Identity Certificate
    c) Create a payment processing Certificate
  4. Write the code for your app for data decryption.

Find detailed information about how to apply this decryption mode in the “Integration” and “Process flows" chapters.

This decryption mode requires more effort on your side, most notably

  • Decrypting the Apple Pay payment token.
  • Generating of public keys.
  • Creating certificate signing requests (CSRs).

We recommend implementing it only if you

  • Prefer handling data encryption yourself.
  • Want to access the payment token before processing the actual payment.

If you choose this decryption mode, make sure to meet the necessary PCI compliance type. Apple Pay follows the EMV® Payment Tokenisation Specification – Technical Framework v1.0 regulation. As tokens are not PCI-relevant data, you need to comply to SAQ-A. However, if you use our JavaScript SDK, a different level may apply. Contact your acquirer for more information

Was this page helpful?

Do you have any comments?

Thank you for your response.