Apple Pay

General information

Apple Pay is a digital wallet provided by Apple that enables customers to make payments on websites and through iOS mobile applications without the need to enter full payment data each time.

There are two ways to integrate Apple Pay:

• WhiteBoot hosted integration (the Apple Pay payment button is located on our payment page).
• Integration with the Apple Pay API (placing an Apple Pay payment button on your site).
  

Before starting the integration process, you should:

1. Register in the merchant portal.
2. Read the list of acceptable products.
3. Ensure that your website uses HTTPS and supports TLS.

WhiteBoot hosted integration

You can easily add Apple Pay as a payment method to your website or mobile application with WhiteBoot's hosted integration. You don't need to make any additional settings as the Apple Pay payment button will be displayed on our payment page. Contact WhiteBoot support to add this payment method.

caution

When using hosted checkout in iframe mode or a payment widget, for security reasons, the Apple Pay method is only supported on devices with Safari version 17 or higher.

Integration using hosted checkout or a payment widget allows initiating payments via Apple Pay from browsers other than Safari, Mobile Safari, WebKit, and others built on it, as well as from devices running operating systems other than macOS and iOS.

Payment process when checkout/payment widget is opened from a desktop device:

1. The user clicks the Apple Pay button.
2. A modal window with a QR code from Apple opens on the payment page.
3. The user scans the QR code using an Apple mobile device and completes the payment on it.
4. The payment processing result is displayed on the page.

The payment process when the checkout/payment widget is opened from an Apple mobile device works similarly to how it functions in the Safari browser (without the need to scan a QR code).

caution

QR code-based payment is available on mobile devices running iOS version 18 or later. On Android devices, this functionality is not supported, and the Apple Pay button is not displayed.

When the hosted checkout is loaded or the payment widget is initialized, the system checks whether Apple Pay is supported on the customer’s device. If the Apple Pay SDK indicates that the method is not supported, the Apple Pay button in the checkout/payment widget will be inactive, and a message will be displayed next to it stating that the method cannot be used on this device.

Integration with Apple Pay API

To add Apple Pay as a payment method to your website or mobile app through Apple Pay API, you need to follow these steps:

1. Create an Apple developer account associated with the Apple Developer Program or Apple Developer Enterprise Program.
2. Obtain a personal merchant ID from Apple.
3. Read and comply with Apple's Branding Guidelines for setup.

To complete the integration, follow these steps:

Step 1: Creating a Merchant ID

1. Sign in to your Apple developer account.
2. Proceed to the “Certificates, Identifiers & Profiles” tab.
3. In the "Identifiers" section, select "Merchant ID".
4. Click the "+" button in the top right corner to add a new merchant ID.
5. Fill in the required fields and click "Continue".
6. Click "Register" to confirm your details.

Step 2. Creating a merchant certificate:

1. From the “Certificates, Identifiers & Profiles” tab, select an identifier in the sidebar, then choose a merchant identifier from the pop-up menu at the top right.
2. Select your merchant ID.
3. In the "Merchant Identity Certificate" section for Apple Pay, click "Create Certificate".
4. Create a certificate signing request on your device, and then click "Continue".
5. Click "Choose file".
6. Select the certificate file with the .certSigningRequest extension in the dialog box that appears.
7. Click "Continue".
8. Click "Download".
9. The certificate file with the ".cer" extension will be saved in the "Downloads" folder.

Step 3. Creating a merchant domain (optional):

This step is only necessary if you want to use Apple Pay on your website.

1. Sign in to your Apple developer account.
2. Go to the “Certificates, Identifiers & Profiles” tab and select an identifier in the sidebar, then select a merchant identifier from the pop-up menu at the top right.
3. Choose your merchant ID.
4. In the “Merchant Domains” section, click “Add Domain”.
5. Enter the full domain name and click “Save”.
6. Click “Download” to get the domain verification file and place it in the specified location and click “Verify” to confirm the domain ownership.
7. Click “Done” to complete the process.

Step 4. Verifying the merchant domain

1. Sign in to your Apple developer account.
2. Under the “Certificates, Identifiers & Profiles” section select an identifier in the sidebar, then select a merchant identifier from the pop-up menu at the top right.
3. Choose your merchant ID.
4. In the "Merchant Domains" section, click "Verify" next to the domain you added in Step 3 and follow the further instructions to complete the verification process.

To use Apple Pay on your website, make sure your server meets the requirements specified in the Apple Developer Portal.

Integration of Apple Pay on a website

1. Familiarize yourself with the instructions and features of the Apple Pay payment method.
2. Ensure that your device or browser is compatible with Apple Pay.
3. Configure the payment request structure.
4. Complete merchant validation.
5. Initiate a payment session and process the payment.
6. Send the payment data to the WhiteBoot API (refer to the next section "Charging").

Charging:

To charge a payment card stored in Apple Pay, send a direct payment creation request with properties.instrument_method.

Apple Pay data must be sent in the properties object:

Parameter	Type	Required	Description
pos_id	UUID	✅	Merchant's identifier (POS_ID)
mode	MODE	✅	direct
method	METHOD	✅	Payment method (auth or purchase)
amount	Number	✅	Transaction amount. Must be a positive number. The number of decimal digits must be less than or equal to 2 (e.g., 100.00, 250, 50.50)
currency	CURRENCY	✅	Transaction currency (ISO_4217)
description	String	✅	Payment description
order_id	String	✅	Unique identifier of order
order_3ds_bypass	String	✅	3-D Secure flow option
customer_id	String		Customer's identifier in merchant's system
customer_fname	String	✅	Customer's first name
customer_lname	String	✅	Customer's last name
customer_patronym	String		Customer's patronym
customer_email	String	✅	Customer's email
customer_phone	String	✅	Customer's phone
customer_ip	String	✅	Customer's IP address
customer_country	String	✅	Customer's country (ISO 3166-1 alpha-2). For instance, UA for Ukraine
customer_city	String	✅	Customer's city
customer_birthday	String	✅	Customer's birthday (format: yyyy-MM-dd)
server_url	URL		Webhook notification will be sent to this URL
result_url	URL		Customer will be redirected to this URL after payment
payload	String		Field for merchant custom data. Max 4000 symbols.
validation_url	String		Preflight request will be sent to this URL
browser_fingerprint	Json	✅	Browser fingerprint. These parameters could be used in 3DS 2.0 verification.
properties.instrument_type	String	✅	wallet
properties.instrument_method	String	✅	APAY
properties.state	String	✅	Customer's state
properties.address	String	✅	Customer's address
properties.post_code	String	✅	Customer's postal code

info

The properties.instrument_method field determines which wallet payment method is displayed on the payment page. Allowed values:

Value	Displayed on the payment page
APAY	Apple Pay only
AGPAY	Apple Pay and Google Pay

Request example:

{
  "mode": "direct",
  "method": "purchase",
  "currency": "EUR",
  "amount": 11.52,
  "description": "Payment 100500001A3248877485",
  "payway": "wallet",
  "customer_fname": "Tom",
  "customer_lname": "Hanks",
  "customer_email": "tom.hanks@example.com",
  "customer_phone": "61432068613",
  "customer_country": "AU",
  "customer_city": "Angle Vale",
  "customer_ip": "194.183.171.239",
  "properties": {
    "instrument_type": "wallet",
    "instrument_method": "APAY",
    "address": "Al. Jana Pawla II",
    "post_code": "00-823",
    "state": "FR"
  },
  "pos_id": "2affde24-3257-4fb5-805d-ff4a77ea72ac",
  "order_3ds_bypass": "supported",
  "order_id": "ef53a22d675742939c3005c127892cf4",
  "server_url": "https://callback.blackhole.com/callback",
  "result_url": "https://example.com/result",
  "browser_fingerprint": {
    "browserColorDepth": "24",
    "browserScreenHeight": "860",
    "browserScreenWidth": "1600",
    "browserJavaEnabled": "false",
    "browserLanguage": "en-US",
    "browserTimeZone": "Europe/Kiev",
    "browserTimeZoneOffset": "-120",
    "browserAcceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "browserIpAddress": "127.0.0.1",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.146 Safari/537.36"
  }
}

Further processing of the request follows the standard payment process used in direct integration.