Apple Pay
Introduction
Apple Pay is a contactless mobile payment and digital wallet service by Apple. It allows users to make secure payments with Apple devices, such as iPhones, iPads, and Apple Watches, using NFC technology. This enables both in-store and online payments without needing to enter card details.
Apple Pay transactions are processed with high security through tokenization, which replaces the actual card number with a unique device-specific number. Each transaction is authenticated by Face ID, Touch ID, or a device passcode. Apple Pay can be used for one-time transactions as well as for recurring payments, depending on the merchant's integration.
Apple Pay is available in numerous global regions and supports a wide range of currencies, enabling cross-border payment experiences. For online and in-app payments, the KC UPCF Web SDK securely collects payment details, which are then transmitted to Apple's servers for processing and authorization. The entire flow keeps sensitive data hidden from the merchant, providing customers with a secure and easy payment experience.
Workflows and Transaction Types
Integration Flow for Merchants
Merchants can integrate Apple Pay for both in-app and web-based transactions, facilitating seamless payment processes for their customers. For integration details, see the Apple Pay Authorization for Guest Payment and Apple Pay Capture guides.
CIT (Customer Initiated Transactions)
Customer-initiated transactions refer to payments where the customer actively engages in the checkout process, selecting Apple Pay and authenticating the transaction using biometric verification such as Face ID or Touch ID, or a passcode. These transactions can be one-time payments for guest users or purchases made by registered users with stored credentials.
Apple Pay CIT is designed for seamless online and in-app payments, providing a secure and convenient experience without requiring the merchants to store sensitive card details. Merchants can integrate Apple Pay CIT using KontoCloud's UPCF Web SDK and APIs to facilitate real-time authorization. For a detailed breakdown of the CIT flow for Apple Pay, refer to the documentation here.
MIT (Merchant Initiated Transactions)
Merchant-initiated transactions allow automated payments without requiring the customer's presence at the time of processing. These transactions are typically used for subscriptions, recurring payments, or cases where delayed or incremental payments are required. Merchants must obtain initial consent during a CIT transaction to store payment details securing before initiating an MIT transaction. Apple Pay MIT payments can be executed based on previously stored credentials without requiring re-authentication from the customer.
MIT workflows include subscription payments (scheduled charges for services, such as monthly memberships), incremental payments (additional charges for services exceeding an initial authorization), delayed charges (payments processed after the service is completed), and unattended MIT payments, used for transactions where the customer is not available. Specific workflows for MIT with can be found here.
Apple Pay can be stored as a payment option for unattended MIT payments. Merchants may securely store Apple Pay details for future charges under specific conditions, with more details here.
Apple Pay supports transactions only with Visa and Mastercard.
Cancellations and Refund
Merchants can process cancellations and refunds for Apple Pay directly through API integration. The refund process follows standard payment industry guidelines and is initiated through the Apple Pay Capture API. Refunds can be processed for full or partial amounts, depending on the merchant's refund policy. Detailed processes are outlined in the Apple Pay Capture.
Storable Payment Option (SPO)
Storing Apple Pay is allowed only in case of subscriptions and unattended MIT payments.
Apple Pay can be stored as a payment option (SPO), supporting recurring payments and other transactions without re-entering payment details. Merchants integrating Apple SPO must ensure compliance with Apple's security policies and regulatory requirements, including proper tokenization and secure storage. Unauthorized storage or usage outside of approved use cases is not permitted. For instructions on storing Apple Pay, refer to the Store New Payment Option documentation.
Transaction Status Flow
Apple Pay transactions progress through standard status phases, such as Authorized, Captured, Refunded, and Canceled, depending on the transaction type and workflow.
KC UPCF Web SDK integration
Apple Pay uses the KC UPCF Web SDK, please refer to this section.
Customizable Apple Pay Button
To customize the Apple Pay button within an API request, include the appleButtonType and appleButtonStyle parameters in criteria (see example below). The "type" parameter defines the text displayed on the button, such as a standard payment label or a subscription-related prompt, while "style" controls the button's visual theme to match different background and branding requirements. These parameters determine how the Apple Pay button is generated on the page, ensuring flexibility in its presentation. By specifying these attributes, merchants can align the button's appearance with their checkout flow while maintaining compliance with Apple's UI guidelines.
Example request
Path:
POST {baseURL}/account/7228905548/storedPaymentOptions/initAdd
Header:
Content-Type: application/json
Accept-Language: en-US
X-Auth-Token: eyJjb25uZW***AwMjZ2PTQifQ==
User-Agent: ***
{
"programCode": "JPMCONS",
"partnerReference": "e70015bf-2b69-4811-8e07-4d579915dfbe",
"accnoType": "01",
"criteria": [
{
"name": "appleMerchantDomain",
"value": "your-shop.com"
},
{
"name": "appleButtonType",
"value": "plain"
},
{
"name": "appleButtonStyle",
"value": "white-outline"
}
],
"paymentOptionCode": "APPLPAY",
"localDate": "2025-01-30",
"localTime": "100744"
}
The following parameters can be configured:
| appleButtonType | Representation |
|---|---|
| buy |  |
| continue |  |
| donate |  |
| pay |  |
| plain |  |
| set-up |  |
| book |  |
| check-out |  |
| subscribe |  |
| appleButtonStyle | Representation |
|---|---|
| black |  |
| white |  |
| white-outline |  |
Multiple Domains Support
To support multiple merchant domains for Apple Pay, the API request can include the appleMerchantDomain parameter within the criteria object (also listed in the example above). This parameter enables merchants to specify additional domain where the Apple Pay button can be displayed, provided the domain has been whitelisted with Apple. If the parameter appleMerchantDomain is not provided or if the specific domain is not properly registered, the Apple Pay button will not be rendered. This requirement is to ensure that the payment request originates from an authorized source.
The registered domain automatically extends to its sub-directories as listed below, allowing Apple Pay transactions on localized pages without requiring separate configurations or registrations with Apple.
your-shop.com
your-shop.com/de
your-shop.com/fr
Merchants must align with their Product Solution Specialist to ensure all relevant domains are configured within the backend program settings before initiating Apple Pay transactions. The domain should be provided without "https://", as the API handles secure connections internally.
If there is a mismatch between the domain registered for Apple Pay and the domain where the Apple Pay button is embedded, and which was provided in the API request, the Apple Pay button will not be displayed during checkout.
Apple Pay Integration Prerequisites
Integration of Apple Pay payment option includes registration of the merchant, verification of the testing domain and testing of the new payment option. Once the testing of the new payment option is done and verification of the production domain is completed, the payment option is ready to go live.
The dedicated Product Solution Specialist will be your partner during the integration process.
1. Registration with JPM MPS
The following information must be provided to the Product Solution Specialist prior to starting the registration procedure:
-
Merchant's web shop testing domain.
-
Merchant's legal name that will be shown to consumer in the checkout phase.
2. Testing Apple Pay on the test environment
The test devices must be enrolled with Apple as the sandbox devices.
To enroll the device, visit https://developer.apple.com/apple-pay/sandbox-testing/
Before using the device to test Apple Pay, check whether the device is compatible with Apple Pay: Devices compatible with Apple Pay.
The production device can be used for sandbox testing, but the "Check for Apple Pay" option in Safari settings should be disabled.
If you are unable to enroll the test device in Apple Sandbox follow the steps below.
- Create a new email address (that is not used or linked to the existing live user) to be used for sandbox testing as your Apple ID.
- Initial password for the Apple ID.
Register this email on developer.apple.com using the initial password and contact the dedicated Product Solution Specialist with this information.
3. Integration prerequisites for Production
Before launching to production, another verification file for the production domain has to be verified by Apple.
- The merchant provides the Product Solution Specialist with the production domain where the webshop will be hosted.
- The Product Solution Specialist provides the merchant with the Apple verification file for production.
- The merchant hosts the verification file on the production environment of the webshop where the Apple JavaScript will be hosted and publicly available.
- Apple verifies the production domain, and it is possible to go live.
The file should be publicly accessible for verification on the following domain:
your-shop.com/.well-known/apple-developer-merchantid-domain-association.rtf
Do not modify the verification file provided by the Product Solution Specialist.
In case the same device is used for testing on both testing and production environment, enable Check for "Apple Pay" option in Safari settings.
Useful links when integrating Apple Pay
- Apple Pay on the Web Interactive Demo
- Apple Pay on the Web - Developer Documentation
- Apple Pay on the Web - Human Interface Guidelines
- Acceptable Use Guidelines for Apple Pay on the Web
Payment Options Test Data
For testing Apple Pay in the sandbox environment, follow the instructions here: Apple Pay - Sandbox testing.