Skip to main content

Set up Apple Pay

Zuora

Set up Apple Pay

This article describes the instructions for setting up Apple Pay on the following gateway integrations by using either the JavaScript SDK approach or the REST API approach:

  • Chase Paymentech Orbital (Latest version)
  • Checkout.com
  • CyberSource, Payment API v2.0
  • Vantiv (Now Worldpay) Gateway
  • Stripe v2
  • Chase Paymentech (Orbital) Gateway 7.0.1 Integration (supports only the REST API approach)

If you are already using one of the approaches for Apple Pay integration, using the other approach will not affect your existing integration. You cannot create Apple Pay payment methods through the UI.

Zuora’s approaches for supporting Apple Pay payment methods on the preceding gateway integrations and on Adyen Integration v2.0 are different. For instructions about setting up Apple Pay on Adyen Integration v2.0, see Set up Adyen Apple Pay.

Set up Apple Pay through the JavaScript SDK approach

You can add Apple Pay to your checkout flow by integrating with a JavaScript SDK provided by Zuora. The Apple Pay button can be displayed in Safari browsers according to your customization. If end users do not have Apple Pay enabled on their devices, the Apple Pay button is still displayed and the end user can follow a wizard to set up a payment method.

The following diagram shows how the Apple Pay JavaScript SDK integration works in a checkout experience:

apple-pay-sdk-flow.png

To integrate with Zuora’s JavaScript SDK for Apple Pay setup, complete all of the following tasks:

  1. Ensure you complete prerequisite tasks before the integration.
  2. Register your domains with Apple Pay.
  3. Implement the server-side API integration.
  4. Implement the client-side SDK integration.

By using Zuora's JavaScript SDK integration, you do not need to create your own Apple Pay certificate for your web integration, because you can process payments through Zuora's Apple Pay certificate.

Prerequisites

  • Understand guidelines and requirements from Apple:
    • Ensure that you have understood Apple guidelines for incorporating Apple Pay into your websites.
    • Your server must meet some requirements for secure communications with Apple Pay. See Apple Pay documentation for details.
  • Ensure that the requirements for the gateway are met:
    • Ensure that your gateway instance in Zuora supports implementing Apple Pay integration through the JavaScript SDK, and you have signed up for a merchant account for the payment gateway. You can find gateway integrations that support Apple Pay integration through SDK at the beginning of this article.
    • If you plan to implement Apple Pay on the Chase Orbital gateway and you have an existing Chase Orbital gateway account, make sure it is using the Salem Platform. See Chase Paymentech (Orbital) Gateway for more information.
    • If you plan to implement Apple Pay on the Stripe v2 gateway, contact Stripe for gated access to the Processing Apple Pay Decrypted Tokens API.

Register your domains with Apple Pay

To use Apple Pay, you must register your web domains that will show the Apple Pay button, including top-level domains and sub-domains. You need to register the domains used in both production and testing. Complete the following steps to register your domain with Apple Pay.

  1. Download and unzip the domain-verification file (apple-developer-merchantid-domain-association.zip) that will be used for domain registration with Apple Pay.
  2. Under the following path, host the domain-verification file with the name apple-developer-merchantid-domain-association for each domain you want to use. Ensure that the domain-verification file is accessible.
    https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association
  3. Register your domain with Apple Pay through either of the following methods:
  • Use the Register an Apple Pay domain API operation to register your domain with Apple Pay. The following operations are available to manage your registered domains:
  • Register your domain through the UI:
    1. Click your username in the upper right and navigate to Settings > Payments > Setup Payment Page and Payment Link
    2. Click the E-Wallets tab.
    3. In the Apple Pay section, if you have not downloaded the domain-verification file, click download and then host it as described in step 2.
    4. Click Add Domain
    5. Enter your domain that will show the Apple Pay button, select Accept and Agree to Apple Pay Web Terms and Conditions, and then click Save.

    The registered domain is listed in the Apple Pay section. To unregister the domain, click Delete.

Implement server-side API integration

Use the Create a payment session REST API operation to create a payment session on your server. To prevent malicious price tampering on the client side, always decide the charge amount on the server side. The response of this API operation contains a token for the payment session data. Send the token back to the client to use in step 3 of the client-side SDK integration.

For details about how to construct the API request, see Create a payment session in the API Reference.

Here are examples of the request and response.

Request:

{
    "accountId":"402880de8779e14f018779e82905000f",
    "processPayment": true,
    "currency": "USD",
    "amount": "100",
    "paymentGateway":"e884322ab8c711edab030242ac120004"
}

Response:

{
    "token":"402880de8779e14f018779e82905000f"
}

Implement client-side SDK integration

This section provides instructions on implementing the client-side SDK integration and a code example.

Procedure

Complete the following steps to implement the JavaScript SDK integration on the client side:

  1. Import Zuora’s JavaScript SDK to your page:
    <script src="https://cdn.zuora.com/payment/v1/zuora-payment.js"></script>
  2. Create a container for the Apple Pay button on your checkout page and place it where you want the payment method form to be rendered. Specify an ID. Replace payment-request-button with the ID you want to use.
    <div id="payment-request-button">
        <!-- The Apple Pay button will be inserted here. -->
    </div>
    
  3. Initiate an instance of the Zuora object with the token returned from the Create a payment session API operation. This token is required for identifying your website to Zuora.
    const zuora = Zuora(token);
  4. Create a configuration object and define the following configuration properties and events:
    • Button style properties
    • Payment request objects
    • A callback function to handle successful responses
    • A callback function to handle error responses

    You can configure the options listed in the following tables for button properties and payment request data objects.

    Button style properties:

    Button property Description
    environment Required

    Type: enum

    Specify your Zuora environment with one of the following allowed values:

    For more information about Zuora environments, see Zuora Data Centers and Zuora Testing Environments.

    style Specify the following properties to define the button style:
    • buttonType: A string that indicates the button type that you can display to initiate Apple Pay transactions. For details about allowed values, see the following articles in Apple’s documentation:
    • buttonStyle: A string that indicates the supported appearance for an Apple Pay Button. For details about allowed values, see the following articles in Apple’s documentation:
    • locale: A string that indicates the languages and regions for the Apple Pay button. For details about allowed values, see ApplePayButtonLocale in Apple’s documentation.

    Payment request objects:

    Payment request object Description
    country Required.

    The ISO 3166 country codes for the country or region of your principal place of business. This is often the location for settling the payment. See ApplePayPaymentRequest documentation for more information.

    currency Required.

    The ISO 4217 currency code for the payment. See ApplePayPaymentRequest documentation for more information.

    totalPriceLabel Required.

    The description of the payment item. See ApplePayPaymentRequest documentation for more information.

    amount Required.

    The total amount for the payment. See ApplePayPaymentRequest documentation for more information.

    supportedNetworks

    Specify any of the following card networks that will be supported by your Apple Pay integration:

    • American Express
    • Discover
    • JCB
    • MasterCard
    • Visa

    The default value is:

    ['amex', 'jcb', 'masterCard', 'discover', 'visa']

    For more information about this object, see ApplePayPaymentRequest documentation for more information.

    For more information about the supported card networks for each gateway integration, see Overview of payment methods supported by Zuora payment gateway integrations.

    You can also use CSS properties to display Apple Pay buttons. Here is an example. For more information, see Display an Apple Pay button using CSS in Apple’s documentation.

    .apple-pay-button {
    --apple-pay-button-width: 140px;
    --apple-pay-button-height: 30px;
    --apple-pay-button-border-radius: 5px;
    --apple-pay-button-padding: 5px 0px;
    }

    For the event that the Apple Pay payment method is created or the payment is processed (if processPayment is set to true in the Create a payment session REST API operation), you can define a callback function to handle successful responses and a callback function to handle error responses. For error codes available for now, see Error codes. We are continuously improving the codes and messages.

    Example:

    const configuration = {
        environment: "api_sandbox",
        paymentRequest: {
            country: "US",
            currency: "USD",
            totalPriceLabel: "TestShop",
            amount: 1599,
            supportedNetworks: ['amex', 'jcb', 'masterCard', 'discover', 'visa']
        },
        style: {
            buttonStyle: "black",
            buttonType: "buy",
            locale: "en-US"
        },    
        onSuccess: function (response) {
            console.info('paymentMethodId: ' + response.paymentMethodId);
            console.info('paymentId: ' + response.paymentId);
        },
        onError: function (response) {
            console.error('code: ' + response.code);
            console.error('message: ' + response.message);
        }
    };
    
  5. Create an instance of the button element, pass in your configuration for the button, and mount the button element to the container for displaying the Apple Pay button. Replace payment-request-button with the ID specified in step 2.
    zuora.create('ApplePay', configuration).mount("#payment-request-button");

Code example for client-side integration

const zuora = Zuora('vIMyxqZKEk7gzUQtGZ1M1fTJBMHhKZH1');
const configuration = {
    environment: "api_sandbox",
    paymentRequest: {
        country: "US",
        currency: "USD",
        totalPriceLabel: "TestShop",
        amount: 1599,
        supportedNetworks: ['amex', 'jcb', 'masterCard', 'discover', 'visa']
    },
    style: {
        buttonStyle: "black",
        buttonType: "buy",
        locale: "en-US"
    },
    onSuccess: function (response) {
        console.info('paymentMethodId: ' + response.paymentMethodId);
        console.info('paymentId: ' + response.paymentId);
    },
    onError: function (response) {
        console.error('code: ' + response.code);
        console.error('message: ' + response.message);
    }
};
zuora.create('ApplePay', configuration).mount("#payment-request-button");

Error codes

The following table lists the error codes returned in the onError callback function.

Error code Description
PAYMENT_SESSION_CANNOT_BE_REUSED The payment session is invalid because it is reused. A payment session can only be used for one payment transaction. Refresh your session token to initiate a new session for the new transaction.
AMOUNT_INCONSISTENT The amount received from the client is not consistent with the amount in the payment session.
APPLE_PAY_UNAVAILABLE The device does not support processing payments with Apple Pay. Ensure the device supports Apple Pay and the web browser is Safari.
NETWORK_IS_NOT_SUPPORTED The card network is not supported. Ensure the card network is one or any of the following values:
  • amex 
  • jcb
  • masterCard 
  • discover 
  • visa

Process the payment

Zuora will handle the payment processing and complete the payment. You do not need to implement any integration for this.

Test your integration

We suggest that you test your integration by using a live card with a test gateway. You can make test payments by using the live card without it being charged. If you must use an Apple Pay testing card, submit a request to Zuora Global Support.

Apple Pay payments are processed through multiple parties, such as the payment gateway, the card network, Apple Pay, and your integration with Zuora. You might encounter issues beyond Zuora’s control, such as a known issue with Discover test cards that currencies other than USD are not supported. If you encounter any issues during your testing, you can submit a request to Zuora Global Support. Zuora will actively work with you to investigate the problems. If the problem is with other parties, please contact the relevant parties for assistance.

Set up Apple Pay through the REST API approach

You can implement Apple Pay integration by using the Create an Apple Pay payment method REST API operation.

Prerequisites

Complete the following steps to configure Apple Pay:

  1. Use your Apple Pay developer account to register merchant ID and the merchant domain for your organization. See Getting Started with Apple Pay for details. 
  2. Sign up for a merchant account for a payment gateway according to your needs. 
    • If you have an existing Chase Orbital gateway account, make sure it is using the Salem Platform. See Chase Paymentech (Orbital) Gateway for more information. 
    • If you have an existing CyberSource payment gateway account, make sure you are also using the CyberSource, Payment API v2.0 gateway integration in Zuora. See CyberSource Payment Gateway for more information.
  3. Contact Zuora Global Support to generate a Certificate Signing Request file (.certSigningRequest extension) for you. Zuora Global Support will then send the CSR file to you.
  4. You need to upload the CSR file on the website of Apple Pay, download Apple certification file (.cer extension), and then send it back to Zuora Global Support together with your Apple Pay merchant ID.
  5. You need to complete several integration steps to make Apple Pay functional on your website. For example, register and validate your website domain as described in Configuring your environment. For more information, see Implementing Apple Pay.

Create Apple Pay payment methods through REST API

After you have completed the configuration, you can use the Create an Apple Pay payment method REST API operation to create an Apple Pay payment method.