{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-documentation/get_started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Apple Pay","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"apple-pay","__idx":0},"children":["Apple Pay"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Apple Pay"]}," is a popular digital wallet and mobile payment service provided by Apple Inc. It allows users to make payments using their Apple devices, such as iPhones, iPads, and Macs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide provides an overview of how to integrate Apple Pay into your payment form using the Embedded SDK."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is highly recommended to have a basic understanding of how to set up the embedded SDK and create a simple checkout experience before diving into Apple Pay. If you haven't already, please refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/get_started/process_payments/embedded_sdk_v3/quick_start"},"children":["Quick Start Guide"]}," to get up and running with the embedded SDK."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you can start accepting Apple Pay payments, you must ensure that you meet the prerequisites outlined in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/get_started/additional_resources/apple_pay"},"children":["Set-Up Apple Pay"]}," guide. This includes configuring your domain and obtaining the necessary certificates."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuring-the-embedded-sdk","__idx":3},"children":["Configuring the Embedded SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once your domain is verified, you can proceed to configure the embedded SDK to accept Apple Pay payments."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To enable Apple Pay in your payment form, you can initialise an Apple Pay component using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createApplePay"]}," method provided by the embedded SDK."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"required-configuration-fields","__idx":4},"children":["Required Configuration Fields"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When configuring the Apple Pay component, there are a couple of required fields you need to provide:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantName"]},": The name of the business as it should appear to customers during the Apple Pay checkout process."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantCountryCode"]},": The two-letter ISO country code representing the country where your business is located (e.g., \"US\" for the United States, \"GB\" for the United Kingdom)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the Apple Pay component is configured, you can mount it to a container element in your HTML to display the Apple Pay button to customers. When customers click the button, they will be guided through the Apple Pay checkout process."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is a simple example of how to configure the embedded SDK to render the Apple Pay button on your checkout page:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"Apple Pay Configuration Example","header":{"title":"Apple Pay Configuration Example","controls":{"copy":{}}},"source":"// Create Apple Pay instance using the default Apple Pay configuration\nconst applePay = createApplePay(controller, {\n    merchantName: 'Fish & Chips Ltd',\n    merchantCountryCode: 'GB',\n});\n\n// Mount the apple pay button to the specified container in the HTML\napplePay.mount(\"#apple-pay-container\");\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"submitting-the-payment","__idx":5},"children":["Submitting the Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a customer clicks the Apple Pay button and completes the payment process, the Apple Pay component will emit a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentSessionResult"]}," event containing the result of the payment attempt. You can listen for this event to handle the payment result and submit the payment accordingly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once this is received, you can pass the result object to a payment handling function to finalise the payment and receive the final payment result."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"Apple Pay Payment Submission Example","header":{"title":"Apple Pay Payment Submission Example","controls":{"copy":{}}},"source":"applePay.on(\"paymentSessionResult\", (event) => {\n    handlePaymentResult(event.result);\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"allowing-credit-cards","__idx":6},"children":["Allowing Credit Cards"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the Apple Pay integration allows customers to pay using either Debit or Credit cards. If you want to restrict payments to only Debit cards, you can set the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowCreditCards"]}," configuration option to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's an example of how to configure the embedded SDK to allow only Debit cards:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"Allow Only Debit Cards Example","header":{"title":"Allow Only Debit Cards Example","controls":{"copy":{}}},"source":"const applePay = createApplePay(controller, {\n    merchantName: 'Fish & Chips Ltd',\n    merchantCountryCode: 'GB',\n    allowCreditCards: false, // Set to false to allow only Debit cards\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"shipping-configuration","__idx":7},"children":["Shipping Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your business requires ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["shipping information"]}," for orders, you can configure the embedded SDK to collect shipping details during the Apple Pay checkout process. This is done using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shippingConfig"]}," configuration object, which allows you to specify the following fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," (array): An array of shipping options that the customer can choose from. Each option should include:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," (string): A unique value to identify the shipping option."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," (string): A descriptive label for the shipping option (e.g., \"Standard Shipping\", \"Express Shipping\")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," (string): A detailed description of the shipping option."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," (number): The cost of the shipping option in the smallest currency unit (e.g., cents for USD). It must be a non-negative integer."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedCountryCodes"]}," (array): An array of two-letter ISO country codes representing the countries where shipping is available (e.g., [\"US\", \"GB\"]). If not specified, shipping will be available to all countries."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requiredContactFields"]}," (array): An array of contact fields that are required from the customer. Possible values include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalAddress"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," (string): The type of shipping. Possible values are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storePickup"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["servicePickup"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's an example of how to configure the embedded SDK with shipping options for Apple Pay:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"Apple Pay Shipping Configuration Example","header":{"title":"Apple Pay Shipping Configuration Example","controls":{"copy":{}}},"source":"const applePay = createApplePay(controller, {\n    merchantName: 'Fish & Chips Ltd',\n    merchantCountryCode: 'GB',\n    shippingConfig: {\n        options: [\n            {\n                id: 'standard',\n                label: 'Standard Shipping',\n                description: '5-7 business days',\n                amount: 500,\n            },\n            {\n                id: 'express',\n                label: 'Express Shipping',\n                description: '1-2 business days',\n                amount: 1000,\n            },\n        ],\n        allowedCountryCodes: ['US', 'CA'],\n        requiredContactFields: ['name', 'postalAddress'],\n    },\n});\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When customers proceed to checkout using Apple Pay, they will be presented with the shipping options you have configured. The selected shipping option and any collected shipping information will be included in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentSession"]}," object returned."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customising-the-apple-pay-experience","__idx":8},"children":["Customising the Apple Pay Experience"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Ryft embedded SDK v3 offers a variety of configuration options to customise the appearance and behaviour of the Apple Pay payment approach to better fit your website's design and user experience. This includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Button styling options: you can choose from different text and style options for the Apple Pay button to match your website's branding. This can be configured using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RyftApplePayDisplayConfig"]}," object (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://web-sdk.ryftpay.com/docs/web/latest/interfaces/Web_SDK.RyftApplePayDisplayConfig.html"},"children":["here"]}," for more details)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Price status indicator: indicates whether the price is final or pending, which can be configured using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RyftApplePayPriceStatus"]}," object (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://web-sdk.ryftpay.com/docs/web/latest/types/Web_SDK.RyftApplePayPriceStatus.html"},"children":["here"]}," for more details)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find more information on the available configuration options for customising the Apple Pay experience in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://web-sdk.ryftpay.com/docs/web/latest/interfaces/Web_SDK.RyftApplePayConfig.html"},"children":["RyftApplePayConfig"]}," documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-example","__idx":9},"children":["Complete Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is a complete working example that combines:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["all the features covered in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/get_started/process_payments/embedded_sdk_v3/quick_start#complete-example"},"children":["Quick Start"]}," guide"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apple Pay integration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apple Pay shipping configuration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apple Pay payment submission handling"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","data-title":"Complete Apple Pay Integration Example","header":{"title":"Complete Apple Pay Integration Example","controls":{"copy":{}}},"source":"<!DOCTYPE html>\n<html lang=\"en\">\n\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <title>Ryft Card Form</title>\n\n    <!-- Only if using the script tag method to install the SDK -->\n    <script src=\"https://web-sdk.ryftpay.com/embedded/latest/ryft.min.js\"></script>\n</head>\n\n<body>\n\n    <div class=\"Ryft--paysection\">\n        <form id=\"ryft-pay-form\" class=\"Ryft--payform\">\n            <div id=\"apple-pay-container\"></div>\n            <div id=\"ryft-pay-error\"></div>\n        </form>\n    </div>\n\n    <script type=\"module\">\n        import { createController, createApplePay } from '@ryftpay/web';  // If using npm to install the SDK\n        // const { createController, createApplePay } = window.Ryft;  // If using the script tag method to install the SDK\n\n        // // Returned when creating a Payment Session\n        const clientSecret = \"\";\n        // Available in the Ryft Portal\n        const publicKey = \"\";\n        // The unique identifier for the Sub-Account, if using the Platform Fee model\n        const accountId = \"\";\n\n        // Get a reference to the error div\n        const errorDiv = document.getElementById(\"ryft-pay-error\");\n\n        // Initialise Controller\n        const controller = createController({\n            publicKey,\n            clientSecret,\n            // accountId  // Uncomment if using the Platform Fee model\n        });\n\n        // Create Card Form instance using the default card form configuration\n        const applePay = createApplePay(controller, {\n            merchantName: 'Fish & Chips Ltd',\n            merchantCountryCode: 'GB',\n            shippingConfig: {\n                options: [\n                    {\n                        id: 'standard',\n                        label: 'Standard Shipping',\n                        description: '5-7 business days',\n                        amount: 500,\n                    },\n                    {\n                        id: 'express',\n                        label: 'Express Shipping',\n                        description: '1-2 business days',\n                        amount: 1000,\n                    },\n                ],\n                allowedCountryCodes: ['US', 'CA'],\n                requiredContactFields: ['name', 'postalAddress'],\n            },\n        });\n\n        // Listen to validation changes to handle the payment result\n        applePay.on(\"paymentSessionResult\", (event) => {\n            handlePaymentResult(event.result);\n        });\n\n        // Handle the payment result after attempting payment\n        function handlePaymentResult(result) {\n            const session = result.paymentSession;\n\n            // Check the payment session status to determine the outcome of the payment\n            // If the status is Approved or Captured, the payment was successful\n            if (session.status === \"Approved\" || session.status === \"Captured\") {\n                console.log(\"Payment Successful\", session);\n                errorDiv.innerHTML = \"<p style='color: green;'>Payment Successful!</p>\";\n                return;\n            }\n\n            // If there is a lastError, display the error message to the user and log the error for debugging\n            if (session.lastError) {\n                const lastError = session.lastError;\n                const message = resut.userFacingErrorMessage;\n                console.error(\"Payment Error\", lastError);\n                errorDiv.innerHTML = `<p style='color: red;'>${message}</p>`;\n            }\n        }\n\n        // Mount the apple pay button to the specified container in the HTML\n        applePay.mount(\"#apple-pay-container\");\n\n    </script>\n\n</body>\n\n</html>\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":10},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now that you have successfully integrated Apple Pay into your checkout experience, you can explore additional features and configurations to further customize the payment experience for your customers."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommended next steps include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://web-sdk.ryftpay.com/docs/web/latest/documents/apple-pay.html"},"children":["Apple Pay documentation page"]}," for more examples and detailed information on the available configuration options for Apple Pay."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkout"]}," component to easily enable multiple payment methods and additional features all in a single component. You can refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://web-sdk.ryftpay.com/docs/web/latest/documents/checkout.html"},"children":["Checkout Component"]}," page for more details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handling SDK errors: Implement comprehensive error handling to manage different types of errors that may occur during the payment process, such as validation errors, network issues, or unexpected system errors. This will help you provide a better user experience and ensure that customers are informed about any issues that arise during checkout. You can refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/get_started/process_payments/sdk_errors"},"children":["SDK Errors"]}," page for best practices and examples on how to implement effective error handling in your integration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhook handling: Set up webhooks to receive real-time notifications about payment events, such as successful payments, refunds, or chargebacks. This allows you to automate order fulfillment, update inventory, and keep customers informed about their transactions. You can refer to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/documentation/get_started/webhooks"},"children":["Webhooks documentation"]}," for more details on how to set up and manage webhooks with Ryft."]}]}]},"headings":[{"value":"Apple Pay","id":"apple-pay","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Configuring the Embedded SDK","id":"configuring-the-embedded-sdk","depth":2},{"value":"Required Configuration Fields","id":"required-configuration-fields","depth":3},{"value":"Submitting the Payment","id":"submitting-the-payment","depth":3},{"value":"Allowing Credit Cards","id":"allowing-credit-cards","depth":2},{"value":"Shipping Configuration","id":"shipping-configuration","depth":2},{"value":"Customising the Apple Pay Experience","id":"customising-the-apple-pay-experience","depth":2},{"value":"Complete Example","id":"complete-example","depth":2},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Apple Pay"}},"lastModified":"2026-03-16T15:28:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/documentation/get_started/process_payments/embedded_sdk_v3/apple_pay","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}