# **Apple Pay** This guide explains how to implement Apple Pay payments with xMoney. Our API provides flexible options for accepting Apple Pay payments through different integration methods. ## Overview Integrate Apple Pay with xMoney to provide a seamless checkout experience for your customers. This guide will walk you through the steps needed to integrate Apple Pay into your website using Twispay/xMoney as the payment processor. > Since September 2019, the Strong Customer Authentication (SCA) regulation has required businesses across Europe to implement additional authentication measures for online payments. Apple Pay fully complies with SCA, as its payment process already includes a built-in authentication layer, such as biometric verification (Face ID, Touch ID) or passcode authentication. By integrating Apple Pay, you agree to Apple's [terms of service](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). ## Prerequisites Before you begin, ensure you have the following: 1. **xMoney** merchant account. With your account, you will be given a `siteId` and a secret unique key (aka `apiKey`). This key is used to authenticate and communicate with our servers securely. The `apiKey` can be found in the merchant account on the following url: [https://merchants.xmoney.com](https://merchants.xmoney.com) For **test accounts** use the Sandbox environment from the [Merchant Dashabord](https://merchants.xmoney.com) Under the "Sites" menu – clicking the number found at column **#** will bring up a site details window. The `apiKey` is listed in the Website details view as "Private key" ***Note:*** * *The apiKey is unique for each website – if you had a test account, the apiKey used for tests is not the same as the one you will need to use for the live environment.* * *Integrate Apple Pay API with xMoney as your gateway. Follow the procedure in the Apple Pay documentation to integrate your [web](https://developer.apple.com/documentation/apple_pay_on_the_web) application.* 1. A **website running on HTTPS** (Apple Pay requires a secure connection). 2. A working xMoney integration with our checkout secure page or directly with our API. For checkout secure page you can find details on how to configure an order request using our documentation found [here](/guides/checkout/hosted-checkout) For API (server to server) integration details can be found [here](https://docs.xmoney.com/api/reference/order/create-an-order) > Supported card networks are: - Visa - Mastercard ## Accept a payment using Apple Pay in your Website Below is the option best suited for your integration. Please refer to Apple's [branding guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay) to correctly incorporate the Apple Pay brand on your website. Hosted checkout The Apple Pay digital wallet button will be displayed on our checkout payment page. To enable this feature, we will activate the option in your account. If you encounter any issues, please contact [support@xmoney.com](mailto:support@xmoney.com) to confirm that Apple Pay has been activated. > Merchants must adhere to the Apple Pay [Acceptable Use Guidelines for Websites](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). Inline checkout When using the [Inline Checkout (xMoney Payment Form)](/guides/checkout/inline-checkout), you can show an Apple Pay button directly inside the embedded payment form by configuring the applePay options at initialization time. As soon as Apple Pay is **enabled** and the shopper’s device/browser supports it (for example Safari on eligible Apple devices), the Apple Pay button will be rendered alongside other available payment methods. > **Before you begin** Before the Apple Pay button can appear inside the Inline Checkout widget, the following conditions must be met. Apple Pay will only be displayed and will work properly if all prerequisites are correctly completed. **Apple Pay must be enabled in your xMoney account** Apple Pay support needs to be activated for your merchant profile. If Apple Pay is not yet enabled for your account, please contact your xMoney account manager or [support team](mailto:support@xmoney.com). Once activated, Apple Pay becomes available as a payment method you can expose in the inline checkout. **Your domain must be verified with Apple** Apple requires every merchant domain to be validated before Apple Pay can be presented on the web. xMoney handles the configuration on Apple’s side, but to complete the validation you must host a specific file on your domain. You will receive a domain verification file from xMoney, for example: ``` apple-developer-merchantid-domain-association ``` To validate your domain create a director `/.well-known/` at the root of your website’s domain and upload the verification file exactly as provided into: ``` https:///.well-known/apple-developer-merchantid-domain-association ``` After the file is in place, xMoney completes the verification process with Apple. Once the domain is approved, Apple Pay will work as expected in your inline checkout. **1. Add the applePay options to the Payment Form** In your existing **XMoneyPaymentForm** initialization, add the applePay block under options: ```ts const sdk = new window.XMoneyPaymentForm({ container: "payment-form-widget", publicKey: PUBLIC_KEY, payload, checksum, sessionToken, userId, options: { locale: "en-US", appearance: customThemeStyles, // 👇 Enable Apple Pay button applePay: { enabled: true, appearance: { style: "black", // "white" | "black" | "white-outline" type: "buy", // Label shown on the button radius: 8, // Border radius in px }, }, }, onReady: () => setIsReady(true), onError: (err: any) => console.error("❌ Payment error", err), onPaymentComplete: (data: unknown) => { // your logic here }, }); ``` That’s all that’s needed on the frontend side to display the Apple Pay button in the inline checkout. If Apple Pay is not supported on the shopper’s device or is not available in their browser, the button will simply not be shown and the customer can continue with the other payment methods. **2. Apple Pay configuration options** The applePay configuration lives under options: ```ts options: { applePay?: { enabled?: boolean; appearance?: { style?: "white" | "black" | "white-outline"; radius?: number; type?: | "add-money" | "book" | "buy" | "checkout" | "contribute" | "continue" | "donate" | "order" | "plain" | "pay" | "reload" | "rent" | "set-up" | "subscribe" | "support" | "tip" | "top-up"; }; }; } ``` Options explained: - enabled - Default: false - When set to true, Apple Pay is exposed as an available payment option in the inline checkout. - When false or omitted, the Apple Pay button is not rendered. - appearance.style - Type: "white" | "black" | "white-outline" - Controls the visual style of the Apple Pay button to better match your site’s design or theme. - appearance.radius - Type: number - Sets the border radius (in pixels) for the button (e.g. 4, 8, 12). - If omitted, a default radius is applied. - appearance.type - Type: one of: - "add-money" | "book" | "buy" | "checkout" | "contribute" | "continue" | "donate" | "order" | "plain" | "pay" | "reload" | "rent" | "set-up" | "subscribe" | "support" | "tip" | "top-up" - Controls the label/intent shown on the Apple Pay button (for example "buy", "checkout", or "subscribe"). For more design guidelines please check [Human Interface Guidelines > Apple Pay > Buttons and Marks](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Button-types) on Apple Official Website **3. Example: minimal configuration** If you just want to turn on Apple Pay with default appearance: ```ts options: { applePay: { enabled: true, }, } ``` This will enable the Apple Pay button using the default style and label, and will only be shown when Apple Pay is supported on the shopper’s device and already enabled for your xMoney account. Merchants must add here to the Apple Pay [Acceptable Use Guidelines for Websites](https://developer.apple.com/apple-pay/acceptable-use-guidelines-for-websites/). ## Accept a payment using Apple Pay in your iOS App #### Prerequisites Your app must: - Use the PassKit framework - Support iOS 9 or later - Follow the [Apple Pay Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/apple-pay) - Successfully pass App Store review More details about how to configure the app can be found on the official [Apple Pay Programming Guide](https://developer.apple.com/documentation/passkit/apple_pay/). #### 1. Setup your integration To start the setup follow [this guide](https://developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay). For requesting a payment token you will need to use the following: - Make sure your merchant identifier is properly configured - You have the necessary certificates for payment processing Supported card networks are: - Visa - Mastercard #### 2. Add the Apple Pay button Add the Apple Pay button to your app by following [Apple's guidelines](https://developer.apple.com/documentation/passkit/offering-apple-pay-in-your-app). This ensures you're using the correct button style and appearance. #### 3. Handle the result - Get the payment token from the payment authorization - From your API make a POST /order request to xMoney API and include the token info in `transactionOption` as shown below: ``` { "digitalWallet":{ "walletType":"applePay", "data": "insert your received encrypted payment token from Apple Pay here (Base64 encoded)" } } ``` #### 4. Test your integration Follow [Apple's guidelines](https://developer.apple.com/apple-pay/sandbox-testing/) for testing your Apple Pay integration. #### 5. Go live with Apple Pay Follow [Apple's instructions](https://developer.apple.com/documentation/passkit/apple_pay/setting_up_apple_pay_requirements) to prepare your app for production and submission to the App Store. ## Go Live * Ensure your **xMoney API keys** are correct for production. * Test real transactions to confirm proper payment processing. Keep your Private Key safe! Your Private Key is a sensitive piece of information. **Never** share it publicly or expose it in client-side code. Anyone with access to your Private Key could potentially make unauthorized transactions on your behalf. ## **Additional Resources** * [Apple Pay Documentation](https://developer.apple.com/documentation/) * [xMoney API](https://docs.xmoney.com/api/introduction) By following these steps, you will have a functional Apple Pay integration with xMoney, offering customers a smooth and secure checkout experience.