# Apple Pay™ on Web Accept Apple Pay™ in your website using Finix. Buyers that use Safari as their browser have the option to use Apple Pay as a payment method when making online purchases. This guide details how to start accepting Apple Pay on your website using Finix. Dues and Assessments We recommend that you pass the address field listed in the steps below. If the address is not passed, you will be charged additional dues and assessments per transaction from the card network. ## Step 1: Onboard with Apple Start by familiarizing yourself with [the prerequisites](/guides/online-payments/digital-wallets/apple-pay) for using Apple Pay™ with Finix. Core Customers If you are a Core customer, instead of Steps 1 or 2 please go to the Application you want to accept Apple Pay. ## Step 2: Register on the Finix Dashboard Before you can begin accepting Apple Pay, you need to first verify and register your domain with Apple. You can complete this step with the Finix Dashboard. After you've registered the domain, download the verification file from file and host it on your website. Don't close the modal until you've hosted the CSR file. Do not click Submit on Step 3 unless you've uploaded the CSR file generated by Finix in the steps below. To register on the Finix Dashboard: 1. Login to your [Finix Dashboard](https://finix.payments-dashboard.com/Login) and click **Developer.** 2. Click the tab **Alt Payment Methods**. 3. Click **Add Web Domain** and follow the instructions to host the verification file. ![Apple Pay Finix Dashboard](/assets/apple-pay-finix-dashboard.da46fab3d03526604c5b31bfa43c63d637b6fc2be5cc8416f8c02558381657f9.08ff7529.png) ## Step 3: Add the Apple Pay Library Now that you've verified and registered your domains with Apple, you need to add the Apple Pay library. Include this script in your website to add Apple Pay's Library so your website can make calls to Apple Pay’s API. ```javascript Apple Pay Library Snippet ``` ## Step 4: Add the Apple Pay Button Now that you've added the Apple Pay library, add an HTML element and name it `apple-pay-button`. Please note that Apple requires the button to be named `apple-pay-button`. To demo all of the Apple Pay button styles, see [Apple Pay's interactive demo](https://applepaydemo.apple.com/). ```html Apple Pay Button ``` Safari Only The Apple Pay button only renders in Safari. | Field | Type | Description | | --- | --- | --- | | `buttonstyle` | *string*, **optional** | Color of the button. Available values are **black**, **white**, and **white-outline** | | `type` | *string*, **required** | There are a variety of button types that you can use on your website to initiate the transaction. They include: Buy (default), Plain, Add Money, Book, Checkout, Continue, Contribute, Donate, Order, Pay, Reload, Rent, Set Up, Subscribe, Support, Tip, Top Up. | | `locale` | *string*, **required** | Set the language of the button. | ## Step 5: Create and Begin Apple Pay Session Now that we have added the Apple Pay button, you need to instantiate `ApplePaySession` to create and begin an Apple Pay session. Do this by invoking the `begin` function. To collect a billing address from buyers, pass in `requiredBillingContactFields`. Collecting Address If address is not collected, fees will apply. ```javascript Apple Pay Session var createAndStartApplePaySession = function(description, amount) { var applePaySession = new ApplePaySession(6, { "countryCode": "US", "currencyCode": "USD", "merchantCapabilities": ["supports3DS"], "supportedNetworks": [ "visa", "masterCard", "amex", "discover"], "total": { "label": description, "amount": amount }}, "requiredBillingContactFields": ["postalAddress"] ); applePaySession.begin(); } ``` #### Begin Apple Pay Session Function Arguments | Field | Type | Description | | --- | --- | --- | | `countryCode` | *string*, **optional** | The ISO country code. | | `currencyCode` | *string*, **required** | The currency code of the locale. | | `merchantCapabilities` | *string*, **required** | The payment types, such as credit or debit, supported by the merchant. The value **supports3DS** is required. | | `supportedNetworks` | *string*, **optional** | The payment networks the merchant supports. Available values are: amex, cartesBancaires, chinaUnionPay, discover, eftpos, electron, elo, girocard, interac, jcb, mada, maestro, masterCard, mir, privateLabel, visa, vPay. | | `total` | *object*, **required** | The label field is a short, localized description of the line item. The amount field is the monetary amount of the line item that follows this format: **0.00.** | | `requiredBillingContactFields` | *string*, **optional** | Pass in **postalAddress** to obtain a postal address as well as the buyer's name after the buyer authorizes the transaction. If you do not retrieve the address to pass to Finix, fees will apply. | ## Step 6: Create and Validate an Apple Pay Merchant Session Now that you have begun an Apple Pay session, validate and complete an [Apple Pay merchant session](/api/payment-instruments/createapplepaysession). Use the instantiated `applePaySession` object from Step 4 to call the `onvalidatemerchant` function. This returns a `validation_url` from the response. ### Merchant Identifier Value The `merchantIdentifier` value corresponds to a Merchant Identity begining with a prefix `IDxx`. There are two options for which value to pass in. #### Option 1 (Default): Application Owner Identity ID If the Apple Pay button will be hosted on your domain, use your application identity ID here. This flow is common if you have just website hosting all of your checkout flows. This is the default option for Direct Merchants and most platforms. You can find the Application Owner Identity ID from the [`merchant#identity`](/api/merchants/getmerchant#merchants/getmerchant/t=response&c=200&path=identity) resource you use to generate payments. #### Option 2: Merchant Owner Identity ID If you are a Platform that hosts websites on custom urls, you should provide the owner identity of your merchants. An example would be a Platform creating websites for their sellers all hosted on custom urls. We recommend reaching out to our support team if you have a flow that fits this criteria. #### Sample Javascript ```javascript Validate Merchant Session var validateMerchantSession = function(applePaySession) { applePaySession.onvalidatemerchant = function(event) { try { var validationURL = event.validationURL console.log("Validating merchant with url: " + validationURL ); if (validationURL) { var request = { provider: APPLE_PAY, validation_url: validationURL, merchant_identifier: merchantIdentity, domain_name: "www.finixtestmerchant.com", display_name: "Finix Test Merchant" } fetch( // call to your server which would then call Finix's /apple_pay_sessions { method: "POST", request, headers }).then((response) => { const sessionDetails = response['session_details'] // need to unstringify response object var merchantSession = JSON.parse(sessionDetails); applePaySession.completeMerchantValidation(merchantSession); }) } else { console.log("Merchant validation failed"); } } catch(err) { console.log(err); throw err; } } } ``` Next, pass the `validation_url` into the subsequent API request which is a POST to `apple_pay_sessions`. Finix returns a `merchantSession` object which you can use in the next step. ```shell Apple Pay Session Request curl https://finix.sandbox-payments-api.com/apple_pay_sessions \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USwV2ayDfbTwjUmrftEBKhgk:9bf27419-0ef6-40f5-bce7-3b0eafb1ac88 \ -d '{ "display_name": "Finix Test Merchant", "domain": "www.finixtestmerchant.com", "merchant_identity": "IDmULj61C8ke6Y7qQiKENJ7", "validation_url": "https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession" }' ``` ```json Apple Pay Session Response { "id": "APPLEPAYSESSION_xxx", "created_at": "2021-11-22T23:58:19.50Z", "updated_at": "2021-11-22T23:58:19.50Z", "session_details": "{\"epochTimestamp\":1640213041060,\"expiresAt\":1640216641060,\"merchantSessionIdentifier\":\"SSH1524BA9006A944B8B9B8FB60227D9990_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\"nonce\":\"a5ee8554\",\"merchantIdentifier\":\"23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"domainName\":\"tj.ngrok.io\",\"displayName\":\"Christmas Shopping\",\"signature\":\"...\",\"operationalAnalyticsIdentifier\":\"Christmas Shopping:23D5E1F154400B277E14CC8361878AA0AAFD46B2DF74003C7587B256269102BD\",\"retries\":0}", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/apple_pay_sessions/APPLEPAYSESSION_xxx" } } } ``` #### HTTP Request `POST https://finix.sandbox-payments-api.com/apple_pay_sessions/` #### Request Arguments | Field | Type | Description | | --- | --- | --- | | `display_name` | *string*, **required** | This will be the merchant name shown to users when making a purchase via Apple Pay with Touch ID. | | `domain` | *string*, **required** | The domain where the buyer is initiating the payment. | | `merchant_identity` | *string*, **required** | The `merchant_identity_id` used when registering the business with Apple Pay through our registration API. | | `validation_url` | *string*, **required** | A validation URL that will be provided by the Apple SDK front-end for every payment. | ## Step 7: Create a Payment With the merchant validated, Touch ID gets prompted for the buyer in between steps 5 and 6. Once the buyer completes Touch ID and their fingerprint is verified, the `onpaymentauthorized` function gets called. Next, Apple Pay returns a token to your front-end which needs to be passed to your server. ```javascript Create Payment var processPayment = function (applePaySession) { applePaySession.onpaymentauthorized = function (event) { try { //token received from Apple var paymentToken = event.payment; if (paymentToken) { console.log("Payment token from Apple: " + paymentToken); // extract billing details addressData = { country: paymentToken.billingContact.countryCode, postal_code: paymentToken.billingContact.postalCode, }; name = billingDetails.givenName + " " + billingDetails.familyName; // send Finix API stringified form of the isolated token var third_party_token = { token: paymentToken.token, }; var stringifiedPaymentToken = JSON.stringify(third_party_token); // call the server to handle the orchestration of Finix calls processPaymentFromServer( stringifiedPaymentToken, addressData, name ); applePaySession.completePayment(applePaySession.STATUS_SUCCESS); console.log( "Finix processed transaction successfully with token: " + paymentToken ); } else { console.log( "Payment token from Apple is null - payment failed to process." ); applePaySession.completePayment(applePaySession.STATUS_FAILURE); } } catch (err) { console.log(err); throw err; } }; }; ``` Then, your server needs to pass the payment token as a `third_party_token`, the address data as `address`, and include the value for `name` when creating a [Payment Instrument](/api/payment-instruments). ```shell Payment Instrument Request curl https://finix.sandbox-payments-api.com/payment_instruments \ -H "Content-Type: application/json" \ -H 'Finix-Version: 2022-02-01' \ -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \ -d '{ "identity": "IDgWxBhfGYLLdkhxx2ddYf9K", "merchant_identity": "IDpYDM7J9n57q849o9E9yNrG", "name": "John Smith", "third_party_token": "{\"token\":{\"paymentMethod\":{\"network\":\"barcode\",\"type\":\"credit\",\"displayName\":\"\"},\"transactionIdentifier\":\"AE514ADAA44E9C3A0A862C7E4EDEE43C422556FA4748B045F1764860557E8EE6\",\"paymentData\":{\"data\":\"IOg9H5\\/hdpccvHZ03ESJwlJXFlmcnI18WXTSOHOPA82ewYoWVyEMiy63HCsdejXsHIR8a+N\\/5aR24OeJrkxheck2AAl5o1LLJ7jL+75scnf7Z55uQmtVyKITTkH22LrC6E6SgMnXaefJYOTUcG1Veqb\\/dXtpPzqaKACEKDkbVivpDk+A2iX5PLROFTMRgmb9a0HYwHOnVGQzXwiHkX1g6f1R4rILUyMaQ5qLxCplE1t\\/guEYmkGBtOb\\/v8+GRDTl8YrC1tOe\\/cs4aQm4cAKJktFQUTbfAApNFBnKI06mtCM7e7qRna\\/YON3gyci035jA7Zq4kBMo7rQB8puGH6dDqB\\/KsPS6Ps+w688+rqEKz16YUJ\\/LMCOzzBM6bCTOS6eouB1eCh3SJdm\\/lmY=\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4zCCA4igAwIBAgIITDBBSVGdVDYwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE5MDUxODAxMzI1N1oXDTI0MDUxNjAxMzI1N1owXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O\\/0komJPnwPE6OCAhEwggINMAwGA1UdEwEB\\/wQCMAAwHwYDVR0jBBgwFoAUI\\/JJxE+T5O8n5sT2KGw\\/orv9LkswRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlYWljYTMwMjCCAR0GA1UdIASCARQwggEQMIIBDAYJKoZIhvdjZAUBMIH+MIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMDYGCCsGAQUFBwIBFipodHRwOi8vd3d3LmFwcGxlLmNvbS9jZXJ0aWZpY2F0ZWF1dGhvcml0eS8wNAYDVR0fBC0wKzApoCegJYYjaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVhaWNhMy5jcmwwHQYDVR0OBBYEFJRX22\\/VdIGGiYl2L35XhQfnm1gkMA4GA1UdDwEB\\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQC+CVcf5x4ec1tV5a+stMcv60RfMBhSIsclEAK2Hr1vVQIhANGLNQpd1t1usXRgNbEess6Hz6Pmr2y9g4CJDcgs3apjMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN\\/EuT4TNW1WZbNa4i0Jd2DSJOe7oI\\/XYXzojLdrtmcL7I6CmE\\/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu\\/0uSzAPBgNVHRMBAf8EBTADAQH\\/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966\\/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\\/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK\\/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjDCCAYgCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghMMEFJUZ1UNjANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMjA0MDExODE2MjJaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEINpyGxYyGbl1Kj57wU\\/3PijxngHUcidFy9jukG9sccOHMAoGCCqGSM49BAMCBEcwRQIhAPHvbeAIDmJKf2YGS5xcCoySSeCeFf6ThUsKE3UIPWBJAiBQIZZu4wTlZn7R16N+2iTfvuvzJKgeSv8rAs3YM6z56AAAAAAAAA==\",\"header\":{\"publicKeyHash\":\"eOvce9ya55opFC5EXVWlLwzZRVDEY3Hgakf3+C+0zkc=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE3VnkF5JR9cWuYoeT68dUNp\\/2\\/jGaOiid19UfCV9rEkcPomrzFWEZw\\/dN1uU9RTblnrIQPajFj4R2ZKIpYIlkgA==\",\"transactionId\":\"ae514adaa44e9c3a0a862c7e4edee43c422556fa4748b045f1764860557e8ee6\"},\"version\":\"EC_v1\"}}}", "type": "APPLE_PAY", "address": { "country": "USA", "postal_code": 12345 } }' ``` ```json Payment Instrument Response { "id": "PI57stCFVsupV2Hov92NqdM9", "created_at": "2022-10-10T05:38:12.97Z", "updated_at": "2022-10-10T05:38:12.97Z", "address": { "city": null, "country": "USA", "line1": null, "line2": null, "postal_code": 12345, "region": null }, "application": "APgPDQrLD52TYvqazjHJJchM", "created_via": "API", "currency": "USD", "enabled": true, "fingerprint": "FPR88YBDbK4TqYMUNU8t8fbeQ", "identity": "IDgWxBhfGYLLdkhxx2ddYf9K", "instrument_type": "APPLE_PAY", "bin": "370382", "brand": "AMERICAN_EXPRESS", "card_type": "UNKNOWN", "expiration_month": 11, "expiration_year": 2024, "issuer_country": "UNKNOWN", "last_four": "8576", "name": "John Smith", "tags": {}, "type": "APPLE_PAY", "_links": { "self": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI57stCFVsupV2Hov92NqdM9" }, "authorizations": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI57stCFVsupV2Hov92NqdM9/authorizations" }, "transfers": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI57stCFVsupV2Hov92NqdM9/transfers" }, "verifications": { "href": "https://finix.sandbox-payments-api.com/payment_instruments/PI57stCFVsupV2Hov92NqdM9/verifications" }, "application": { "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM" }, "identity": { "href": "https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K" } } } ``` #### Request Arguments | Field | Type | Description | | --- | --- | --- | | `identity` | *string*, **required** | ID of the `Identity` that the card should be associated with. | | `merchant_identity` | *string*, **required** | The `merchant_identity_id` used when registering the business with Apple Pay through our registration API. | | `name` | *string*, **required** | Full name of the registered card holder. | | `third_party_token` | *string*, **required** | Stringified token provided by Apple. Required to process Apple Pay transactions. | | `type` | *string*, **required** | Type of Payment Instrument. Use **APPLE_PAY** for transactions using Apple Pay. | | `address` | *object*, **optional** | Object containing address data. If address is not passed, fees will apply. | `completePayment` will complete the payment authorization with either a successful or failure result. Similar to other Finix transactions, after you receive a successful result, you can create a [`transfer`](/api/transfers) or an [`authorization`](/api/authorizations).