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.

Make sure your website fulfils Apple Pay's requirements before getting started.

Before you can integrate into Finix:

  1. Create an Apple Developer Sandbox Account
  2. Ensure you are logged into this developer account through iCloud on your Macintosh.
  3. You must use Apple Pay test card numbers from their documentation. Please see Apple developer website .
info

This guide is only for supporting Apple Pay on Safari.

Step 1: 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.

To register on the Finix Dashboard:

  1. Login to your Finix Dashboard and click Developer.
  2. Click the tab Alt Payment Methods .
  3. Click Add Web Domain and follow the instructions to host the verification file.
info

If you are a Core customer, instead of Step 1 please go to the Application you want to accept Apple Pay.

Apple Pay Finix Dashboard

Step 2: 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.

Copy
Copied
<script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>

Step 3: 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.

Copy
Copied
<style>
apple-pay-button {
  --apple-pay-button-width: 150px;
  --apple-pay-button-height: 30px;
  --apple-pay-button-border-radius: 3px;
  --apple-pay-button-padding: 0px 0px;
  --apple-pay-button-box-sizing: border-box;
}
</style>
<apple-pay-button buttonstyle="black" type="plain" locale="en"></apple-pay-button>
info

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 4: 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.

Copy
Copied
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.

Step 5: 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.

From step 4, use the instantiated applePaySession object to call the onvalidatemerchant function. This returns a validation_url from the response.

Copy
Copied
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.

Copy
Copied
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"
}'

Example Response

Copy
Copied
{
    "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 6: 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.

Copy
Copied
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);
                // send Finix API stringified form of the token
                var stringifiedPaymentToken = JSON.stringify(paymentToken)

                // call the server to handle the orchestration of Finix calls
                processPaymentFromServer(stringifiedPaymentToken)
                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 and include a value for name when creating a Payment Instrument.

Copy
Copied
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"
	}'

Example Response

Copy
Copied
{
    "id": "PI57stCFVsupV2Hov92NqdM9",
    "created_at": "2022-10-10T05:38:12.97Z",
    "updated_at": "2022-10-10T05:38:12.97Z",
    "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.

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 or an authorization.