Apple Pay: Difference between revisions
new Apple Pay SDK |
|||
| Line 2: | Line 2: | ||
{{TableOfContents}} | {{TableOfContents}} | ||
Apple Pay is a wallet solution created by Apple for Apple customers. It is only accessible in the Apple ecosystem. You can use it with your iPhone, iWatch or with your desktop/laptop Macintosh computer. When it comes to Barion there are two different ways to use this payment option: | |||
* on the Barion Smart Gateway (called hosted mode) | |||
* in their webshop if they integrate the so-called integrated mode | |||
The customer who wants to pay with Apple Pay Wallet must have an Apple device that supports authentication. This could be | |||
* an iPhone, | |||
* a modern MacBook with fingerprint authentication or | |||
* an older MacBook with a paired iPhone | |||
=== Browser support === | |||
Apple Pay behaves differently depending on the customer's browser:<blockquote> | |||
* In Safari, and in any browser built on Apple's WebKit engine (Chrome, Firefox, or Edge on iOS), the button works natively, and the customer confirms the payment with Touch ID or Face ID. | |||
* In other desktop browsers that can't run Apple Pay directly (for example Chrome, Firefox, or Edge on Windows), Apple's SDK automatically shows a QR code that the customer scans with their iPhone's Camera app (requires '''iOS 18 or later''') to complete the payment there. | |||
</blockquote>Furthermore, the customer must fill out their home address and their contact information in their Apple Pay wallet as well. Without this, they won't be able to use their card in their Apple Wallet. This can be done even during the payment process. | |||
This feature is listed as an available payment method on the shop's admin site | |||
In case it is switched off the shop won't be able to display it as a funding source. This won't produce any error message, the Apple Pay option just won't be visible. | |||
=== Hosted mode === | |||
This is the "out of the box" mode that is available on the Barion Smart Gateway. It works in every browser described in the '''Browser support''' section above — natively in '''Safari''' and other WebKit-based browsers, and via the QR code hand-off in other desktop browsers. | |||
If the customer selects the Apple Pay accordion, the Apple Pay button will be visible. | |||
Once the customer clicks the Pay button the Apple Pay screen is displayed. This screen is actually controlled by the device, we don't have any control over it. | |||
On this screen, the customer may change the used credit card, the home address, or the e-mail address. These are all required to pay via Apple Pay. Once the customer approves the transaction everything continues as with a normal card would. | |||
=== Integrated mode === | |||
In integrated mode (called processor mode in Apple documentation) the webshop owner puts the Apple Pay button in their webshop and does not need to redirect the customer to the Barion Smart Gateway. This feature requires custom development from the webshop owner. The shop has to implement the Apple Pay button (instead of just relying on our gateway). To do this, they have to read through [[Apple Pay|this documentation]]. | |||
The Apple Pay button can be displayed anywhere on the webshop. For example, on our demomerchant site is next to the Google Pay button. | |||
This integration requires a developer and is beneficial for shops that want to provide their customer a faster payment experience (since there is no need to redirect them to our gateway). | |||
To enable the button on the merchant's website the website has to be registered at Apple services. To help with this task we created a setting screen in our system. This setting page is available from the shop's setting page. (The one accessible by the owner) | |||
On this page, the owner has to input all the domains that the shop is using for the Apple Pay button. In addition to this the owner also has to upload a domain verification file to its domain. | |||
=== After payment === | |||
After the successful payment, the customer receives the usual confirmation letter, however, the bank card is clearly flagged, so the customer is aware that the payment was funded with a card from their Apple Wallet. | |||
'''Warning:''' The card number displayed here is not the real card number. Apple creates a fake card number to protect the real card, so we are only aware of the fake number. | |||
= Technical implementation = | |||
== Merchants == | |||
The production and non-production environments use different merchants to keep the processing private key secret. Barion has two registered merchants at Apple Pay: | |||
* merchant.com.barion.applepay (used in the production environment) | |||
* merchant.com.barion.test.applepay (used in non-production environments) | |||
This means the certificate installations, domain validations, and registrations must be completed separately in every environment. All necessary files and certificates are in a separate folder here: ''R:\Development\Sensitive\ApplePay\Merchants'' | |||
Certificates for production environment are handled by the Operator team. | |||
== Certificates == | |||
Apple Pay certificates for the Dev|Demo environments are here: ''R:\Development\Sensitive\ApplePay\Merchants''. They were created by the operators, use the following page to create the Apple Pay merchant ID and certificates, and verify the domains: Configuring the environment | |||
There are two certificate files with different purposes. The ''merchant'' certificate is to validate and create Apple Pay sessions and the ''processor'' certificate is to decrypt the payload. Each of the certificates has to contain a private key. The preferred format is P12. | |||
The merchant certificate has to be installed on the Windows certificate store, the application will use it from the Personal container. | |||
From the processing certificate we need the private key only, to retrieve it use the following OpenSSL (3.2.1+ version required) command: | |||
After the PEM file is created, the content of the file should be saved into a text file. This text file is used in the configuration file(ApplePay.ProcessingPrivateKeyPath): | |||
== Changing of the certificates == | |||
Certificates can be obtained from Apple. Apple can only handle one certificate at a time, when the new certificate is enabled, the old one is automatically revoked. Since this process takes about 15-45 minutes to complete, it is advised to do it in a low-traffic period. | |||
Steps: | |||
# Obtain the new certificates from the Apple Developer Portal | |||
# Generate the private key for the certificate as described in the previous point | |||
# Update the appropriate config files (Secure, Api, Admin, Tools.QuedTaskInstaller as of 2023.04.21.) with the new certificate thumbprint and private key | |||
# Enable the new certificates on the Apple Developer Portal | |||
# Deploy the new configs to our servers (since the old certificates are revoked, and the new onew take about 15-45 minutes for the certificates to go live on Apple's side, there will be a downtime of about 15-45 minutes, during this time, ApplePay payments will fail) | |||
# Done :) | |||
== Testing == | |||
Apple Pay on the web can be tested with Apple devices. The minimum OS versions are: | |||
* macOS 10.14.4 | |||
* iOS 12.2 | |||
There are some example message here: ''R:\Development\Sensitive\ApplePay\Sample messages'' | |||
These messages can be posted via Postman using the following API endpoint: | |||
Use the WalletMessage object in the CardInformation object to post the Apple Pay payload. | |||
To test the new cross-browser QR code hand-off (for customers on desktop non-Safari browsers), you need an iPhone running '''iOS 18 or later''' — this is a separate, newer requirement from the general "iOS 12.2" minimum above, which only covers using Apple Pay natively in '''Safari'''. | |||
MacOS is not enough to use Apple Pay. To use Apple Pay on MacOS you should configure Handoff function on the devices, follow this to set up the devices properly. This Handoff requirement applies to '''Safari''' on macOS. Non-Safari desktop browsers (including Chrome or Firefox on macOS) don't need Handoff configured at all — they use the QR code hand-off flow described above instead. | |||
You can test which certificate is used to encrypt the payment data with this command: | |||
The 2023_proc_Certificates.p12 should be the new certificate! | |||
The output of the above script should be the same as that of PaymentData.Header.PublicKeyHash | |||
== Troubleshooting domain association errors == | |||
Some common pitfalls with domain association files can be found below. | |||
* domain association file cannot be reached without authentication | |||
* response doesn’t contain “Content-Type” header with value “application/json” | |||
* merchant’s server only supports TLS 1.3 (Barion uses 1.2 for checking this file) | |||
* merchant has some form of bot/scraping protection enabled, which filters out requests that has a non-browser shaped or missing User-Agent header | |||
If a merchant reaches out about a domain association file problem, you can check these issues via: | |||
* first opening the domain association file on their site from a browser and checking the response | |||
* and if that didn’t bring any results, running the script “Test-ApplePayDomainAssociation.ps1” found in the DeveloperScripts repo | |||
** run this script in Powershell 5.1 | |||
** you can run the script locally, but for more reliable results, use one of the prod-web machines via the help of operators (so the network environment and TLS capabilities match production) | |||
== Contact == | |||
George Maroufidis <[email protected]> | |||
George Maroufidis | Pay eCommerce EMEIA | OneBattersea Power Station, London, SW11 8BZ, United Kingdom | iPhone: +44 7591 916 527 | |||
== Design == | |||
* Apple Pay Marketing Guidelines | |||
* Human Interface Guidelines | |||
== Reference == | |||
* Configuring the environment | |||
* Apple Pay on the web | |||
* PaymentToken | |||
* Sandbox | |||
<blockquote>This article is about directly integrating the Apple Pay button in your webshop. | <blockquote>This article is about directly integrating the Apple Pay button in your webshop. | ||
Revision as of 07:11, 3 September 2026
Apple Pay integration
Apple Pay is a wallet solution created by Apple for Apple customers. It is only accessible in the Apple ecosystem. You can use it with your iPhone, iWatch or with your desktop/laptop Macintosh computer. When it comes to Barion there are two different ways to use this payment option:
- on the Barion Smart Gateway (called hosted mode)
- in their webshop if they integrate the so-called integrated mode
The customer who wants to pay with Apple Pay Wallet must have an Apple device that supports authentication. This could be
- an iPhone,
- a modern MacBook with fingerprint authentication or
- an older MacBook with a paired iPhone
Browser support
Apple Pay behaves differently depending on the customer's browser:
- In Safari, and in any browser built on Apple's WebKit engine (Chrome, Firefox, or Edge on iOS), the button works natively, and the customer confirms the payment with Touch ID or Face ID.
- In other desktop browsers that can't run Apple Pay directly (for example Chrome, Firefox, or Edge on Windows), Apple's SDK automatically shows a QR code that the customer scans with their iPhone's Camera app (requires iOS 18 or later) to complete the payment there.
Furthermore, the customer must fill out their home address and their contact information in their Apple Pay wallet as well. Without this, they won't be able to use their card in their Apple Wallet. This can be done even during the payment process.
This feature is listed as an available payment method on the shop's admin site
In case it is switched off the shop won't be able to display it as a funding source. This won't produce any error message, the Apple Pay option just won't be visible.
Hosted mode
This is the "out of the box" mode that is available on the Barion Smart Gateway. It works in every browser described in the Browser support section above — natively in Safari and other WebKit-based browsers, and via the QR code hand-off in other desktop browsers.
If the customer selects the Apple Pay accordion, the Apple Pay button will be visible.
Once the customer clicks the Pay button the Apple Pay screen is displayed. This screen is actually controlled by the device, we don't have any control over it.
On this screen, the customer may change the used credit card, the home address, or the e-mail address. These are all required to pay via Apple Pay. Once the customer approves the transaction everything continues as with a normal card would.
Integrated mode
In integrated mode (called processor mode in Apple documentation) the webshop owner puts the Apple Pay button in their webshop and does not need to redirect the customer to the Barion Smart Gateway. This feature requires custom development from the webshop owner. The shop has to implement the Apple Pay button (instead of just relying on our gateway). To do this, they have to read through this documentation.
The Apple Pay button can be displayed anywhere on the webshop. For example, on our demomerchant site is next to the Google Pay button.
This integration requires a developer and is beneficial for shops that want to provide their customer a faster payment experience (since there is no need to redirect them to our gateway).
To enable the button on the merchant's website the website has to be registered at Apple services. To help with this task we created a setting screen in our system. This setting page is available from the shop's setting page. (The one accessible by the owner)
On this page, the owner has to input all the domains that the shop is using for the Apple Pay button. In addition to this the owner also has to upload a domain verification file to its domain.
After payment
After the successful payment, the customer receives the usual confirmation letter, however, the bank card is clearly flagged, so the customer is aware that the payment was funded with a card from their Apple Wallet.
Warning: The card number displayed here is not the real card number. Apple creates a fake card number to protect the real card, so we are only aware of the fake number.
Technical implementation
Merchants
The production and non-production environments use different merchants to keep the processing private key secret. Barion has two registered merchants at Apple Pay:
- merchant.com.barion.applepay (used in the production environment)
- merchant.com.barion.test.applepay (used in non-production environments)
This means the certificate installations, domain validations, and registrations must be completed separately in every environment. All necessary files and certificates are in a separate folder here: R:\Development\Sensitive\ApplePay\Merchants
Certificates for production environment are handled by the Operator team.
Certificates
Apple Pay certificates for the Dev|Demo environments are here: R:\Development\Sensitive\ApplePay\Merchants. They were created by the operators, use the following page to create the Apple Pay merchant ID and certificates, and verify the domains: Configuring the environment
There are two certificate files with different purposes. The merchant certificate is to validate and create Apple Pay sessions and the processor certificate is to decrypt the payload. Each of the certificates has to contain a private key. The preferred format is P12.
The merchant certificate has to be installed on the Windows certificate store, the application will use it from the Personal container.
From the processing certificate we need the private key only, to retrieve it use the following OpenSSL (3.2.1+ version required) command:
After the PEM file is created, the content of the file should be saved into a text file. This text file is used in the configuration file(ApplePay.ProcessingPrivateKeyPath):
Changing of the certificates
Certificates can be obtained from Apple. Apple can only handle one certificate at a time, when the new certificate is enabled, the old one is automatically revoked. Since this process takes about 15-45 minutes to complete, it is advised to do it in a low-traffic period.
Steps:
- Obtain the new certificates from the Apple Developer Portal
- Generate the private key for the certificate as described in the previous point
- Update the appropriate config files (Secure, Api, Admin, Tools.QuedTaskInstaller as of 2023.04.21.) with the new certificate thumbprint and private key
- Enable the new certificates on the Apple Developer Portal
- Deploy the new configs to our servers (since the old certificates are revoked, and the new onew take about 15-45 minutes for the certificates to go live on Apple's side, there will be a downtime of about 15-45 minutes, during this time, ApplePay payments will fail)
- Done :)
Testing
Apple Pay on the web can be tested with Apple devices. The minimum OS versions are:
- macOS 10.14.4
- iOS 12.2
There are some example message here: R:\Development\Sensitive\ApplePay\Sample messages
These messages can be posted via Postman using the following API endpoint:
Use the WalletMessage object in the CardInformation object to post the Apple Pay payload.
To test the new cross-browser QR code hand-off (for customers on desktop non-Safari browsers), you need an iPhone running iOS 18 or later — this is a separate, newer requirement from the general "iOS 12.2" minimum above, which only covers using Apple Pay natively in Safari.
MacOS is not enough to use Apple Pay. To use Apple Pay on MacOS you should configure Handoff function on the devices, follow this to set up the devices properly. This Handoff requirement applies to Safari on macOS. Non-Safari desktop browsers (including Chrome or Firefox on macOS) don't need Handoff configured at all — they use the QR code hand-off flow described above instead.
You can test which certificate is used to encrypt the payment data with this command:
The 2023_proc_Certificates.p12 should be the new certificate!
The output of the above script should be the same as that of PaymentData.Header.PublicKeyHash
Troubleshooting domain association errors
Some common pitfalls with domain association files can be found below.
- domain association file cannot be reached without authentication
- response doesn’t contain “Content-Type” header with value “application/json”
- merchant’s server only supports TLS 1.3 (Barion uses 1.2 for checking this file)
- merchant has some form of bot/scraping protection enabled, which filters out requests that has a non-browser shaped or missing User-Agent header
If a merchant reaches out about a domain association file problem, you can check these issues via:
- first opening the domain association file on their site from a browser and checking the response
- and if that didn’t bring any results, running the script “Test-ApplePayDomainAssociation.ps1” found in the DeveloperScripts repo
- run this script in Powershell 5.1
- you can run the script locally, but for more reliable results, use one of the prod-web machines via the help of operators (so the network environment and TLS capabilities match production)
Contact
George Maroufidis <[email protected]>
George Maroufidis | Pay eCommerce EMEIA | OneBattersea Power Station, London, SW11 8BZ, United Kingdom | iPhone: +44 7591 916 527
Design
- Apple Pay Marketing Guidelines
- Human Interface Guidelines
Reference
- Configuring the environment
- Apple Pay on the web
- PaymentToken
- Sandbox
This article is about directly integrating the Apple Pay button in your webshop.
If you simply want to display Apple Pay as a payment option in the Barion Smart Gateway, no further configuration is necessary; pass "ApplePay" in the FundingSources array when preparing a payment.
The appeal of Apple Pay is that it requires only two actions from the customer: selecting the ‘Pay with Apple Pay’ button, and confirming the payment with Touch ID or Face ID.
Another advantage to your Barion shop’s payment workflow is that customers aren’t navigated away from your checkout page when using Apple Pay.
Prerequisites
- access to and being able to modify both your webshop’s front-end and back-end code
- your webshop using HTTPS (having a TLS 1.2 or higher certificate installed) for all its pages that include the Apple Pay button
- Barion Wallet with an approved Barion shop
- the Barion shop complies with Apple’s acceptable use guidelines, including not selling prohibited products or services
Note that Apple’s policies regarding acceptable products and services are more limiting than those of Barion.
It may happen that even though Barion approves your Barion shop to sell a certain item, you will not be allowed to display the Apple Pay button as a payment option for customers to pay for that item.
- an account in the Barion Wallet for each of the currencies that you’d like to accept using Apple Pay
Limitations
- you can’t yet tokenize your customer’s card details when using the Apple Pay button, so recurring payments aren’t available
- Barion currently only supports Apple Pay button on the web, and not on native iOS apps
- regardless of the integration detailed here, the Apple Pay button will only be displayed to your customers if they comply with Apple’s requirements:
- they’re using an Apple Pay-compatible device
- they’re viewing your webshop using a browser that supports Apple Pay
- they’re located in a country or region where Apple Pay is available
Steps
Setting up your Apple prerequisites
When using Barion’s Apple Pay API endpoints, Barion gives you an Apple developer account, and registers a Merchant ID, Payment Processing Certificate, and Merchant Identity Certificate for you as a subsidiary of Barion’s Apple Pay credentials.
Verify and register your webshop’s domain name or names:
- Log in to your Barion Wallet, and go to your Barion shop’s Shops>Actions>Settings screen.
- Click the “Manage Apple Pay settings”, and then “Download domain verification file” to save the verification file for your shop’s domain.
- Save the domain verification file that you downloaded in the
/.well-knowndirectory of all the sites that your specified domains use, making sure of the following:- the file should send the
<mimeMap fileExtension="." mimeType="application/json" />MIME data; - the file must be accessible externally, and not be password-protected, or behind a proxy or redirect;
- the sites must be served over HTTPS.
- the file should send the
- Enter all the domains that you’d like to use Apple Pay on (into whose root you’ve downloaded the domain verification file) in the text box provided, then click “Save”.
Configuring and displaying the Apple Pay button
Load the button script into your checkout page by adding the following script tag inside the page head:
<script src="https://applepay.cdn-apple.com/jsapi/v1.1.0/apple-pay-sdk.js"></script>
This script makes an ApplePaySession available to your site front-end, among other things.
Add the
apple-pay-buttonelement (for example,<div id="apple-pay-button"></div>) to your checkout page, and use the CSS included in the button script to display it.Start a new ApplePaySession when the checkout page loads:
const request = { countryCode: 'US', currencyCode: 'USD', supportedNetworks: ['visa', 'masterCard', 'discover'], merchantCapabilities: ['supports3DS'], total: { label: 'Your Merchant Name', amount: '10.00' } } const applePlaySession = new ApplePaySession(3, request); // add an isSessionCanceled boolean to easily be able to cancel the session if your user abandons the in-progress payment process var isSessionCanceled = false;
The merchant may supply the shipping and billing contact information directly, or request it when starting the ApplePaySession by including the requiredShippingContactFields and requiredBillingContactFields properties in the payment request. More about the Apple Pay payment request here.
-
Make sure to only display the Apple Pay button to users who can use it, by have your webshop’s checkout pages do the following when they load:
Call the applePaySession.canMakePaymentsWithActiveCard or applePaySession.applePayCapabilities method, passing it your Barion shop’s public Id as the merchantId parameter.
If Apple can verify your Barion shop as a registered Apple Pay provider, the method checks the following:
- that your customer's device is capable of using Apple Pay
- that Apple Pay is enabled on your customer's device, and
- that the customer has the details of at least one active and web payment-eligible bank card stored in their Apple Pay wallet.
- Handle the
PaymentCredentialStatusobject that the method returns to make a decision about displaying the Apple Pay button.
Handling payments
Set up your webshop to perform these steps each time a user selects the Apple Pay button.
Set up an event handler for
ApplePaySession.onvalidatemerchantthat notifies your site's back-end, and passes it the event response.Don't call the ValidateSession Barion API endpoint directly from the browser, as this could expose your Barion shop's POSKey.
Have your site's back-end call the ValidateSession Barion API endpoint, passing it the
onvalidatemerchantevent’sValidationUrlattribute.async function validateApplePaySession(POSKey, SessionRequestUrl, ShopUrl) { const url = "https://api.test.barion.com/v2/ApplePay/ValidateSession"; const data = { POSKey, SessionRequestUrl, ShopUrl, }; try { const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(data), }); if (!response.ok) { throw new Error(`Error: ${response.status} ${response.statusText}`); } const result = await response.json(); return result; } catch (error) { // handle the error according to your business logic } } applePaySession.onvalidatemerchant = async function (event) { const validationResult = await validateApplePaySession(POSKey, event.validationURL, ShopUrl); applePaySession.completeMerchantValidation(validationResult.ApplePaySessionResponse); };This event is triggered when the Apple Pay payment sheet is displayed to the customer.
Set up an event handler for
ApplePaySession.onpaymentauthorizedDon't call the StartPaymentWithAppleToken Barion API endpoint directly from the browser, as this could expose your Barion shop's POSKey.
- that calls the StartPaymentWithAppleToken Barion API endpoint, passing it the event’s following attributes:
- token
- shippingContact
- billingContact
Note that
StartPaymentWithAppleTokenis actually a specialized version of the payment/start API endpoint, and so will also require all the usual parameters that you’d pass to that endpoint.async function startApplePayPayment( POSKey, ShippingContact, BillingContact, Token, /** include other required and optional Payment/Start params */ PaymentStartProperties ) { const url = "https://api.test.barion.com/v2/ApplePay/StartPaymentWithAppleToken"; const data = { POSKey, ShippingContact, BillingContact, Token, ...PaymentStartProperties, }; try { const response = await fetch(url, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(data), }); if (!response.ok) { throw new Error(`Error: ${response.status} ${response.statusText}`); } const result = await response.json(); return result; } catch (error) { // handle the error according to your business logic } } const PaymentStartProperties = { PaymentType: "Immediate", }; applePaySession.onpaymentauthorized = function (event) { startApplePayPayment( POSKey, event.paymentInfo.shippingContent, event.paymentInfo.billingContact, event.paymentInfo.Token, PaymentStartProperties ); };This event is triggered when the customer has authorized the Apple Pay payment using their Touch ID or Face ID.
Set up an event handler for
oncancelto implement your business logic for when the user abandons the Apple Pay payment.Make sure that your event handler indicates that the session is canceled so the ApplePaySession’s
completePaymentmethod doesn’t get executed.applePaySession.oncancel = function (event) { // your oncancel business logic isSessionCanceled = true; };Call ApplePaySession.begin to kick off the payment process.
applePaySession.begin();
This starts the merchant validation process that results in
ApplePaySession.onvalidatemerchantbeing triggered.
Testing your implementation
The following steps are needed in order to test your implementation:
- request access by sending an email to [email protected]!
- include an email address, that has no Apple Id yet
- we will register & connect it to our test account
- after that, you will be able to use Apple's test cards