{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Apple Pay Integration"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"apple-pay-integration","__idx":0},"children":["Apple Pay Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accept Apple Pay payments using the Widget SDK."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How It Works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK renders an Apple Pay button directly on your checkout page. When the customer clicks it, the native Apple Pay payment sheet opens with the amount you specified. After the customer authorizes, the SDK delivers a token via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onTokenizationComplete"]},". There is no separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tokenize()"]}," call — the button click is the trigger. For complete reference, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/ui-sdk-reference"},"children":["SDK reference"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK automatically loads the Apple Pay JS SDK, so you don't need to include it separately. On non-Safari browsers (Chrome, Edge, including Windows), the payment sheet is replaced by a code the customer scans with their iPhone (iOS 18+) to authorize the payment there."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A registered Apple Pay merchant identifier"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Domain verification with Apple — you must host the Apple domain verification file at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/.well-known/apple-developer-merchantid-domain-association"]}," on the domain that serves your checkout page. The SDK automatically uses your page's hostname for merchant validation, so the page must be served from the verified domain."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-load-the-sdk","__idx":3},"children":["Step 1: Load the SDK"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-add-a-container","__idx":4},"children":["Step 2: Add a Container"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-initialize-the-sdk","__idx":5},"children":["Step 3: Initialize the SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the Widget with your callbacks, then set the session token with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateSessionToken"]},". The session token must be set before the customer clicks the Apple Pay button."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const wg = new Widget({\n // ...additional options — see UI SDK Reference\n\n onTokenizationComplete: (result) => {\n // result.responseCode === '0', result.paymentMethod === 'applePay'\n // Forward result.token to your backend\n },\n\n onCancel: (payload) => {\n // Customer dismissed the Apple Pay sheet\n // { responseCode: 'E402', responseMessage: 'PAYMENT_CANCELLED', ... }\n },\n\n onError: (error) => {\n // Errors are reported as\n // { responseCode, responseMessage, description } — see Error Codes in the SDK reference\n }\n});\n\nwg.updateSessionToken('');\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-render-the-apple-pay-button","__idx":6},"children":["Step 4: Render the Apple Pay Button"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mount()"]}," with the container selector, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMethod: 'applePay'"]},", and the payment options in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applePay"]}," object. The SDK renders the button and wires up the Apple Pay flow."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"wg.mount('#apple-pay-button', {\n paymentMethod: 'applePay',\n applePay: {\n total: {\n label: 'Nelnet Campus Commerce', // shown next to the total on the sheet\n amount: '75.00'\n },\n partnerInternalMerchantIdentifier: ''\n }\n});\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the customer clicks the button, the native Apple Pay sheet opens with the amount. After they authorize, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onTokenizationComplete"]}," is invoked with the token. If the customer dismisses the sheet, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onCancel"]}," is invoked."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The country and currency are always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},". Supported card networks are Visa, Mastercard, American Express, and Discover."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"applepay-options","__idx":7},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applePay"]}," Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ label, amount }"]}," — the payment sheet total. Both fields are required; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," is a string greater than zero."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["displayName"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Merchant name shown during merchant validation. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total.label"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partnerInternalMerchantIdentifier"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your merchant identifier, used during Apple merchant validation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lineItems"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Itemized breakdown shown on the sheet above the total: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[{ label, amount }]"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multiTokenContexts"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Multi-merchant payment contexts — see below."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurringPaymentRequest"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recurring payment details — see below."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-5-process-the-payment","__idx":8},"children":["Step 5: Process the Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}," to your backend. Your server submits it to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.nelnetpay.com/apis/osi-payments-api/other/processpaymentrequest"},"children":["Payments API"]}," to process the charge."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"multi-merchant-payment","__idx":9},"children":["Multi-merchant payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For platforms that split a single checkout across multiple merchants. Apple Pay generates one token per merchant."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requirements:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer's device must support Apple Pay version 14 or later; otherwise the SDK reports an error via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each context requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partnerMerchantIdentifier"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entityId"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The sum of the context amounts cannot exceed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total.amount"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multiTokenContexts"]}," cannot be combined with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurringPaymentRequest"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Optionally, each context accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantName"]}," (shown on the sheet, defaults to the total label) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantDomain"]}," (defaults to your page's hostname)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"wg.mount('#apple-pay-button', {\n paymentMethod: 'applePay',\n applePay: {\n total: { label: 'Total Amount', amount: '110.00' },\n lineItems: [\n { label: 'AAA University', amount: '100.00' },\n { label: 'BBB Service Fee', amount: '10.00' }\n ],\n multiTokenContexts: [\n {\n partnerMerchantIdentifier: 'TESTCLIENT_a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6',\n entityId: 'A-123',\n merchantName: 'AAA University',\n amount: '100.00'\n },\n {\n partnerMerchantIdentifier: 'TESTCLIENT_a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6',\n entityId: 'B-456',\n merchantName: 'BBB Service Fee',\n amount: '10.00'\n }\n ]\n }\n});\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The merchant session is validated under the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partnerInternalMerchantIdentifier"]}," if provided; otherwise the SDK uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["partnerMerchantIdentifier"]}," from the first context."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recurring-payment","__idx":10},"children":["Recurring payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For subscriptions and other repeat billing. Pass a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurringPaymentRequest"]}," describing the recurring payment; the payment sheet shows it to the customer before they authorize. The resulting NPS token is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["reusable"]}," — your backend charges it through the Payments API on your own schedule. The recurring payment plan (billing schedule, agreement, and any trial pricing) is managed by NPS, not Apple — Apple does not initiate any charges itself."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requirements:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The customer's device must support Apple Pay version 14 or later; otherwise the SDK reports an error via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurringPaymentRequest"]}," requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentDescription"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["regularBilling"]}," (with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},"), and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["managementURL"]},"; the SDK rejects the request with an error if any are missing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cannot be combined with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["multiTokenContexts"]},"."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentDescription"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Plain-language description of the recurring payment, shown on the payment sheet."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["regularBilling"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The recurring line item: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"nobr","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["managementURL"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A page on your site where the customer can manage or cancel the subscription. Apple links to it from the Wallet app, so it must be a real, working URL."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total.amount"]}," (the sheet total) to the recurring amount in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["regularBilling"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"wg.mount('#apple-pay-button', {\n paymentMethod: 'applePay',\n applePay: {\n total: { label: 'Meal Plan Subscription', amount: '9.99' },\n partnerInternalMerchantIdentifier: '',\n recurringPaymentRequest: {\n paymentDescription: 'Campus Meal Plan — billed monthly',\n regularBilling: {\n label: 'Meal Plan Subscription',\n amount: '9.99'\n },\n managementURL: 'https://checkout.example.com/account/subscriptions'\n }\n }\n});\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The customer authorizes once. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onTokenizationComplete"]}," returns the reusable token; store it and submit a Payments API charge each billing cycle."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"complete-example-one-time","__idx":11},"children":["Complete example (one-time)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"\n\n\n \n Checkout\n\n\n Checkout
\n \n\n \n \n\n\n","lang":"html"},"children":[]}]},"headings":[{"value":"Apple Pay Integration","id":"apple-pay-integration","depth":1},{"value":"How It Works","id":"how-it-works","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Load the SDK","id":"step-1-load-the-sdk","depth":2},{"value":"Step 2: Add a Container","id":"step-2-add-a-container","depth":2},{"value":"Step 3: Initialize the SDK","id":"step-3-initialize-the-sdk","depth":2},{"value":"Step 4: Render the Apple Pay Button","id":"step-4-render-the-apple-pay-button","depth":2},{"value":"applePay Options","id":"applepay-options","depth":3},{"value":"Step 5: Process the Payment","id":"step-5-process-the-payment","depth":2},{"value":"Multi-merchant payment","id":"multi-merchant-payment","depth":3},{"value":"Recurring payment","id":"recurring-payment","depth":3},{"value":"Complete example (one-time)","id":"complete-example-one-time","depth":2}],"frontmatter":{"seo":{"title":"Apple Pay Integration"}},"lastModified":"2026-08-19T10:44:35.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/apple-pay","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}