Ingenico Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above
Page topics

Integration

Apple Pay in-app

Ingenico ePayments 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.
How to integrate

Our platform allows you to offer Apple Pay in two ways:

  1. Redirect your customers to our Hosted Checkout Page
  2. Integrate Apple Pay with your native IOS app

1. Integrate with 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
If your customers do not fulfil all of these requirements, our platform does not display the payment button on Hosted Checkout Page

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

    ApplePay2.png
    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
   }
}

2. Integrate via Server-to-server

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

applePayCertificate.png

  • 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 Ingenico ePayments account

First make sure Apple Pay is enabled for your account. To do so contact your account manager at Ingenico ePayments 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.

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" }
}
}