Integrate Apple Pay - Payment Gateway

SaltPay does not do the integration of Apple Pay for payment gateways, it is the sole responsibility of the merchant.

Here below is a step-by-step guide on what is required in order to activate Apple Pay for payment gateways.

Developer information for integrating ApplePay into the payment gateway

Apple Pay requirements

The requirements for using Apple Pay on your website are:

• Your website must comply with the Apple Pay guidelines. For more information, see Acceptable Use Guidelines for Apple Pay on the Web.

• You must have an Apple Developer Account and complete the registration. For more information, see Configuring Your Environment.

• All pages that include Apple Pay must be served over HTTPS. For more information, see Setting Up Your Server.

For design guidance, see Human Interface Guidelines > Apple Pay.

Step 1: Register for an Apple Developer Account and complete the registration

Before you begin, you’ll need:

• An iPhone or an iPad with Touch ID, Face ID, or a passcode enabled, or a Mac with Touch ID or a password enabled. You must use the same device for the entire enrollment process.

• An Apple ID with two-factor authentication turned on. Your Apple ID information must be valid and up to date — including, but not limited to, your first name (given name), last name (family name), address, phone number, trusted phone number, and trusted devices.

• The latest version of the Apple Developer app installed on your device.

• To sign in to iCloud on your device.

Enrolling and Managing your Account in the Apple Developer App - Support - Apple Developer

Start enrollment:

1. Launch the Apple Developer app on the device you want to use for enrollment (ATT. Apple device is needed to finalize the enrollment)

2. Tap or click the Account tab.

3. Sign in with your Apple ID. This can be different than the Apple ID signed in to your device, but must have two-factor authentication turned on.

4. If prompted, review the Apple Developer Agreement and tap or click Agree.

5. Tap or click Enroll Now.

6. Review the program benefits and requirements and tap or click Continue.

Enter your information as the Account Holder

1. If requested, enter your legal first name, legal last name, and phone number. Do not enter an alias, nickname, or company name as your legal name, as doing so will cause a delay in the completion of your enrollment review.

2. You’ll be asked to verify your identity using your driver’s license or government-issued photo ID. Capture your photo ID and tap or click Confirm.

Enter your organization’s information

Follow the steps on the next few screens to provide the following information:

• Entity type.

• Legal entity name. We do not accept DBAs, fictitious businesses, trade names, or branches. The legal entity name will appear as the “seller” for apps you distribute. Example: Seller: ABC Company, Inc.

• D‑U‑N‑S® Number. Your organization must have a D‑U‑N‑S Number so that we can verify its identity and legal entity status. These unique nine-digit numbers are assigned by Dun & Bradstreet and are widely used as standard business identifiers. You can look yours up and request one for free.

• Headquarters address and phone number.

• Website. Your organization’s website must be publicly available and the domain name must be associated with your organization.

• Signing authority confirmation. Confirm that you have the authority to bind your organization to legal agreements and provide the contact information of an employee who can verify your signature authority.

• Optionally, if your organization is a nonprofit, educational, or government organization, you can request a fee waiver.

After you’ve submitted your information, it will be reviewed by Apple. You’ll then receive an email from Apple with next steps.

Complete enrollment and purchase

Once your enrollment information has been verified and approved, you’ll receive an email letting you know that you can complete your enrollment.

1. Launch the Apple Developer app on the device you used for enrollment.

2. Tap or click the Account tab.

3. Sign in with the Apple ID you used for enrollment.

4. Tap or click Continue Your Enrollment.

5. Review the terms of the Apple Developer Program License Agreement and tap or click Agree.

6. Review your annual membership subscription details and tap or click the Subscribe button.

Membership is provided on an annual basis as an auto-renewable subscription that renews until cancelled. You can make your purchase using one of your Apple ID payment methods. ³ If you need to use your organization’s credit card, add it to the Apple ID that’s signed in to your device’s settings. This can be a different Apple ID than the one you use to enroll. A receipt will be emailed to you, and you can resend the receipt to yourself via email at any time from Purchase History in Settings. You can cancel your subscription in Settings up to one day before your annual renewal date, this will cancel your ApplePay membership and the option will be unavailable through the Gateway. Membership fees paid for the year during which you cancel are nonrefundable.

Step 2:

Follow the instructions in Configure Apple Pay on the Web. They guide you to create the following:

• Merchant ID. An identifier you register with Apple that uniquely identifies your business as a merchant able to accept payments. This ID never expires, and you can use it in multiple websites and iOS apps. See Create a merchant identifier for the setup steps.

• Payment processing certificate. A certificate associated with your merchant ID, used to secure transaction data. Apple Pay servers use the certificate’s public key to encrypt payment data. You, or your payment service provider, use the private key to decrypt data to process payments. See Create a payment processing certificate for the setup steps.

• Merchant identity certificate. A Transport Layer Security (TLS) certificate associated with your merchant ID, used to authenticate your sessions with the Apple Pay servers. The merchant identity certificate is only required for Apple Pay on the web; it isn’t needed for apps. See Create a merchant identity certificate for the setup steps.

While your merchant ID never expires, the payment processing certificate, merchant identity certificate, and domain verification do expire. See Maintaining Your Environment for more information.

Register a merchant domain

1. In Certificates, Identifiers & Profiles, click Identifiers in the sidebar, then select Merchant IDs from the pop-up menu on the top right.

2. On the right, select your merchant identifier.

3. Under Merchant Domains, click Add Domain.

4. Enter the fully qualified domain name, then click Save.

5. Click Download, place the downloaded file in the specified location, then click Verify.

6. Click Done.

Choosing an API for Implementing ApplePay on Your Website

Compare Apple Pay JS and Payment Request API to choose the right implementation for your website.

Safari supports two APIs for implementing payment requests: Apple Pay JS API, and the W3C Payment Request API. Both APIs present the same Apple Pay payment sheet on Safari, and offer nearly the same user experience.

To help you decide which API to implement, or whether to implement both, first determine which features your solution requires, and choose the API that matches your needs.

Features of Apple Pay JS API

Use Apple Pay JS API if you depend on any of its unique features:

Granular error handling. You can provide robust error handling:

• Customizable error messages and field indications create a better user experience. See ApplePayError for more information.

• You can report errors the user can correct, even after the user authorizes payment.

• You can retry if an error occurs after the user authorizes payment. With Payment Request API, the user must restart their transaction.

Integration for store cards and cobranded debit/credit cards. When customers with affiliated cards visit your website, you can provide these additional benefits:

• Apple Pay can automatically select the affiliated card instead of the customer's default card.

• You can adjust prices or other terms of a sale for customers using your affiliated card. For example, you might provide free shipping when customers use your cobranded VISA credit card.

Phonetic names. You can request a phonetic name in Apple Pay JS API only.

Features of Payment Request API

Use Payment Request API for these benefits:

• Cross-browser solution. Payment Request API-based code can support a variety platforms and browsers. Apple Pay is available on Safari; other payment methods are available on other browsers and platforms.

• W3C standard candidate API. The Payment Request API is defined by the World Wide Web Consortium (W3C).

Choose an API to Support Your Customers

To better reach your customers, choose an API that works on their devices, as follows:

• Apple Pay JS API: Supported in iOS 10 and later, and macOS 10.12 and later.

• Payment Request API: Supported in iOS 11.3 and later, and Safari 11.1 on macOS 10.12 and later.

When implementing Payment Request API, consider also implementing Apple Pay JS API as a fallback for customers whose devices run an older operating system version.

Checking for Apple Pay Availability

Before displaying an Apple Pay button or creating an Apple Pay session, you must ensure that the Apple Pay JS API is available and enabled on the current device.

To check whether the Apple Pay JS API is available in the browser, verify that the window.ApplePaySession class exists, as shown in the following listing:

Next, check whether payments are possible by calling either canMakePayments or canMakePaymentsWithActiveCard methods, as follows:

• canMakePayments – This method verifies that the device is capable of making Apple Pay payments; it doesn’t verify that the user has a provisioned card for use with Apple Pay on the device. You can call this method at any time.

• canMakePaymentsWithActiveCard – This method verifies both that the device is capable of making Apple Pay payments, and that the user has at least one provisioned card. This method asynchronously contacts the Apple Pay servers as part of the verification process. You can only call this method if you want to default to Apple Pay during your checkout flow, or if you want to add an Apple Pay button to your product detail page.

The following code shows how to check that a payment method is available before displaying an Apple Pay button:

if (window.ApplePaySession) {
    var merchantIdentifier = 'example.com.store';
    var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
    promise.then(function (canMakePayments) {
        if (canMakePayments)
            // Display Apple Pay button here.
    });
}

Displaying Apple Pay Button

Using JavaScript: Apple Developer Documentation

Using CSS: Apple Developer Documentation

Creating an Apple Pay Session

After you've checked that the Apple Pay JS API is available and is enabled on the current device, you're ready to create the payment request and start the session. You can create a session only when a user explicitly asks to make a payment. For example, you can create the session when the user taps the Apple Pay button.

You supply two parameters to ApplePaySession:

• Version number. The Apple Pay version you're using. (See Apple Pay on the Web Version History for version information.)

• Payment Request. An ApplePayPaymentRequest dictionary that contains all the information needed to display the payment sheet.

Creating an ApplePaySession object throws a JavaScript exception if any of the following occur:

• Any Apple Pay JS API is called from an insecure page.

• You pass an invalid payment request. Payment requests are invalid if they contain missing, unknown, or invalid properties, or if they have a total that is zero or less.

• You attempt to create the ApplePaySession outside of a user gesture handler. The exception error "Must create a new ApplePaySession from a user gesture handler" appears.

After the session is created, call its begin method to show the payment sheet.

Listing 1 shows creating a payment request and a new Apple Pay session, and displaying the payment sheet.

Listing 1 Example of constructing an Apple Pay session

var request = {
  countryCode: 'US',
  currencyCode: 'USD',
  supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'],
  merchantCapabilities: ['supports3DS'],
  total: {
    label: 'Your Merchant Name',
    amount: '10.00'
  },
}
var session = new ApplePaySession(3, request);
    

Providing Merchant Validation

As soon as the system displays the payment sheet, the Apple Pay JS API calls your session object’s onvalidatemerchant event handler to verify that the request is coming from a valid merchant. It passes the function an ApplePayValidateMerchantEvent object that contains the validation URL.

Important

The URL you receive can vary, so always use the URL provided in the validationURL property. Your server must provide allow-listed access to all the validation URLs, specified in Setting Up Your Server.

In your onvalidatemerchant function:

1. You call your server, passing it the URL from the event’s validationURL property.

2. Your server uses the validation URL to request a session from the Apple Pay server, as described in Requesting an Apple Pay Payment Session. Never send the request for a merchant session from the client.

3. In response, your server receives an opaque merchant session object.

4. You pass the merchant session object to your Apple Pay session’s completeMerchantValidation method. You can use the merchant session object a single time. It expires five minutes after it is created.

You need a new Apple Pay payment session for each transaction. Your server posts a request using two-way TLS by calling the Apple Pay server’s Payment Session endpoint. Use the Merchant Identity Certificate associated with your merchant ID in the call.

Payment Session Endpoint URL

Endpoint (Global): POST https://apple-pay-gateway.apple.com/paymentservices/paymentSession

Endpoint (China region): POST https://cn-apple-pay-gateway.apple.com/paymentservices/paymentSession

Returns an opaque Apple Pay session object for Apple Pay on the web and for Apple Pay in Apple Messages for Business.

For Apple Pay on the web, you can also use the endpoint POST https://<validation URL>/paymentSession with a fully qualified validation URL that you receive in onvalidatemerchant. Be sure to allow all of the domains listed in Setting Up Your Server.

Important

Ensure that your server accesses only the validation URLs provided by Apple in Setting Up Your Server, and fails for other URLs. Using a strict allow list for the validation URLs is recommended. You must send the payment session request from your server; never request the session from the client.

Request Parameters

merchantIdentifier

Your merchant ID.

displayName

A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. Don’t localize the name. Use only characters from the supported character sets in the fonts listed in the table below.

initiative

A predefined value that identifies the e-commerce application making the request.

initiativeContext

A value you provide based on the initiative.

The values for initiative and initiativeContext depend on the kind of application you’re building:

• For Apple Pay on the web, use “web” for the initiative parameter. For the initiativeContext parameter, provide your fully qualified domain name associated with your Apple Pay Merchant Identity Certificate.

• For Apple Messages for Business, use “messaging” for the initiative parameter. For the initiativeContext parameter, pass your payment gateway URL. See Type Interactive for more information.

On supported models of MacBook Pro, the Touch Bar displays the value you supply for the displayName parameter. The following table lists the valid fonts.

Response

In response to the POST request, your server receives an opaque Apple Pay session object. The session expires after five minutes.

• For Apple Pay on the web, you pass the session object to the completion method, completeMerchantValidation.

• For Apple Pay in Apple Messages for Business, you pass the session object to your Messaging Service Provider (MSP), which handles communicating with Apple Messages for Business on your behalf.

Example

A session request with a JSON payload for Apple Pay on the web.

const options= {
  url: endpointURL,
  cert: merchIdentityCert,
  key: merchIdentityCert,
  method: 'post',
  body:{
    merchantIdentifier: "merchant.com.example.mystore",
    displayName: "MyStore",
    initiative: "web",
    initiativeContext: "mystore.example.com" // Has to match the verified domain
  },
  json: true,
}

The displayName you provide in the payload appears in the Touch Bar like this:

Apple Pay Payment Object

Once the user authenticates with Touch ID or Face ID, the Apple Pay APIs will call back the app / website with a payment object containing the payment data (encrypted) as well as customer information.

Below is an example of the full Apple Pay payment object structure a merchant’s app / website can receive when asking for all the customer information from the payment sheet.

Apple makes no representations or warranties (whether express or implied, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of the use of or reliance on this document), and expressly disclaims all liability, with regard to the subject matter contained herein.

{
    token:{
        paymentData: {
            version:"EC_v1",
            data:"3+f4oOTwPa6f1UZ6tG...CE=",
            signature:"MIAGCSqGSIb3DQ...AAAA==",
            header: {
                ephemeralPublicKey:"MFkwEK...Md==",
                publicKeyHash:"l0CnXdMv...D1I=",
                transactionId:"32b...4f3"
            }
        },
        paymentMethod:{
            displayName:"Visa 1234",
            network:"Visa",
            type:"debit"
        },
        transactionIdentifier:"32b...4f3"
    },
    billingContact:{
        addressLines:[
            "1 Street",
            ""
        ],
        administrativeArea:"",
        country:"United Kingdom",
        countryCode:"GB",
        familyName:"Appleseed",
        givenName:"John",
        locality:"London",
        postalCode:"AB12 3CD",
        subAdministrativeArea:"",
        subLocality:""
    }, 
    shippingContact:{
        addressLines:[
            "1 Street",
            ""
        ],
        administrativeArea:"",
        country:"United Kingdom",
        countryCode:"GB",
        familyName:"Appleseed",
        givenName:"John",
        locality:"London",
        postalCode:"AB12 3CD",
        subAdministrativeArea:"",
        subLocality:"",
        phoneNumber:"01234 567890",
        emailAddress:"<a href="mailto:john.appleseed@apple.com">john.appleseed@apple.com</a>"
    }
}

The main elements of the above payment object are explained as follows:

Learn more about the structure of an Apple Pay payment token here.

Authorizing the Payment

Once the user has authorized themselves on the payment sheet the app / website will receive the Apple Pay payment object outlined in the previous section.

At this point the user has verified their identity using Touch ID or Face ID but a payment has not yet taken place.

The merchant needs to pass the decrypted token information to the payment processor (SaltPay - payment gateway) who can then create an authorization via the payment networks. As stated previously, the merchant will decrypt the payment data themselves.

Decrypting the Payment Data

The Secure Element encrypts the token’s payment data using either elliptic curve cryptography (ECC) or RSA encryption. The encryption algorithm is selected by the Secure Element based on the payment request. Most regions use ECC encryption. RSA is used only in regions where ECC encryption is unavailable due to regulatory concerns.

Full instructions outlining the process for decrypting the payment data can be found here.

Java sample code for decryption is available at request from your Apple Pay contact.

NOTE: The merchant should use the publicKeyHash value, present in the Apple Pay payload, to identify the public key used to encrypt each payload so they can identify the corresponding private key to successfully decrypt. This is especially important as keys/certificates are being transitioned.

Apple makes no representations or warranties (whether express or implied, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of the use of or reliance on this document), and expressly disclaims all liability, with regard to the subject matter contained herein.

Constructing the Authorization Message

Once the payment data has been decrypted, it needs to be sent for authorization. Apple Pay has been designed to use the similar data formatting as a 3D Secure transaction. Creating a successful authorization should be a case of mapping the Apple Pay fields to payment fields used for card/EMVCo token payments.

Once decrypted, the following fields from the Apple Pay data should be mapped to the appropriate data fields used for EMVCo token payments. The following table provides examples of where this data could map to, but it is recommended you seek specific advice from your partner acquirers / networks.

When using ApplePay as payment method, the 3D Secure verification step becomes “Manual”

American Express

Payments using an American Express card may require slightly different mapping to that outlined above. In addition to the above mapping, please use the following table for guidance on mapping Amex payment fields:

© 2021 Apple Inc. All rights reserved. Apple, the Apple logo, Apple Pay, and Wallet are all trademarks of Apple Inc., registered in the U.S. and other countries.