Set up Apple Pay

Step 1. Load zuora.js

Import the Zuora JavaScript client library to your page.

For sandbox environments, use <script src="https://js.zuora.com/payment/sandbox/v3/zuora.js"></script>.

For production environments, use <script src="https://js.zuora.com/payment/v3/zuora.js"></script>.

Step 2. Create a container

Create a container for the Apple Pay button on your page and place it where you want the button to be rendered. Replace payment-form-container with the ID you want to use.

<div id="payment-form-container">
<!-- The Apple Pay button will be inserted here. -->
</div>

Step 3. Render the Apple Pay button

1. Copy the publishable key from Payment Form. In the Zuora UI, click your username in the upper right and navigate to Settings > Payments > Payment Form. On the Publishable Keys tab, copy the key.
2. Initialize an instance of the Zuora object with your publishable key.
3. Populate the configuration parameters and generate a payment session when the end customers click the Apple Pay button. The following table describes the parameters:

   Parameter	Type	Description
   currency	string	Required. The ISO 4217 alphabetic currency code, such as "USD".
   amount	string	Required. The total amount for the payment.
   supportedNetworks	array	Required. The payment networks supported by your Apple Pay integration. Specify the values as an array of strings, such as ["visa", "masterCard", "amex", "discover"] Before specifying this field, check the following information: The networks supported by your payment gateway integration. See the Zuora Knowledge Center article specific to your payment gateway integration for details. The allowed values. See Apple’s documentation for supportedNetworks for details.
   countryCode	string	The ISO 3166-1 alpha-2 code of the country where the transaction is processed, such as "US". If it is not specified, the default value US is used.
   locale	string	The locale code, which is the combination of ISO language code and ISO country code, such as "en_US". If it is not specified, the default value en_US is used.
   buttonType	string	Default: plain 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: ApplePayButtonType Apple Pay Design - Button types
   buttonStyle	string	Default: black 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: ApplePayButtonStyle Apple Pay Design - Button styles
   buttonRadius	string	Default: 7px The button corner radius in pixels, such as 10px.
   buttonHeight	string	The button height in pixels, such as 30px.

   The following parameters should not be specified when rendering the button:

   • The label parameter required by Apple Pay is automatically populated with the value from the Business Name field of the Public Business Information payment setting.

   • The accountId parameter should not be specified when rendering the button. It can be specified when implementing the server-side API integration. See Implement server-side API integration to create payment session.

   • Specifying a gateway instance is not supported when rendering the button. You can do it when implementing the server-side API integration. See Implement server-side API integration to create payment session.

4. Mount the button component to the container.
5. Handle the payment result.  

Here is an example of the code implementation:

<script>
    const publishableKey = "pk_rO0ABXenAF2s7QAF…";
    
    const renderForm = () => {
      const zuora = Zuora(publishableKey);
      zuora.createApplePayButton({
        currency: "USD",
        amount: "10.00",
        countryCode: "US",
        locale: "en_US",
        buttonType: "pay",
        buttonStyle: "white-outline",
        buttonRadius: "20px",
        buttonHeight: "50px",
        supportedNetworks: ["visa", "masterCard", "amex", "discover"],
        createPaymentSession: () => {
          return new Promise((resolve, reject) => {
            fetch("/sdk-test/payment-session.json?seed=" + Math.random(), {
              method: "GET",
            }).then((response) => {
              if (response.ok) {
                return response.json();
              } else {
                return reject("Payment session request is rejected.");
              }
            }).then((data) => {
              return resolve(data.token);
            }).catch((error) => {
              return reject(error);
            });
          });
        },
        onComplete: (result) => {
          console.log("==========");
          console.log("Payment Result");
          console.log("==========");
          console.log(`transaction result: ${JSON.stringify(result)}`);
          alert(`transaction result: ${JSON.stringify(result)}`);
        }
      }).then(function(applePayButton) {
        applePayButton.mount("#payment-form-container")
      }).catch(function(error) {
        console.error(error);
      });
    }
    function resultMessage(message) {
        const container = document.querySelector("#result-message");
        container.innerHTML = message;
      }
</script>

The onComplete function returns result in the following structure:

{
    success: true,
    paymentMethodId?: string;
    paymentId?: string;
}

{
    success: false,
    error: {
        type: string;
        code: string;
        message: string;
    }
}

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. Generate the Apple Pay certificate and send it to Zuora:
   1. 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.
   2. On the Apple Pay website, upload the CSR file, and then download the payment processing certificate.
   3. Send the payment processing certificate back to Zuora Global Support together with your Apple Pay merchant ID.
4. 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 a payment method

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.

Make payments with Apple Pay

After an Apple Pay payment method has been added to a customer account, it can be used to make payments similar to using credit cards. You can use Apple Pay payment methods in all Payments API operations. Recurring transactions through Apple Pay will be processed identically to credit card transactions. Processing Apple Pay transactions is not supported by the legacy CRUD API operations. You can also view the Apple Pay payment method in Zuora UI and process payments through the UI. Like other credit cards, you cannot modify the card type and card number when editing a payment method in Apple Pay.

Prerequisites

• Ensure that you have enabled the Apple Pay functionality for your Adyen merchant account, and built your payment form to retrieve Apple Pay tokens as described in Adyen documentation. 

  You can use either an Adyen Apple Pay certificate or a custom Apple Pay certificate to generate an Apple Pay token. However, Zuora recommends that you take the Adyen certificate approach.

  If you use the Adyen Apple Pay certificate to generate an Apple Pay token, all certificate management work is done on the Adyen side, so you do not need to upload it in Zuora. However, you need to retrieve a Base64 encoded string as a response. This string should be decoded prior to being sent to Zuora. See the Apple Pay session response from Adyen documentation for details. 

  If you use a custom Apple Pay certificate, you are responsible for the generation of the certificate and maintenance of its lifecycle. See Use your own Apple Pay certificate to complete the Apple Pay session validation from Adyen documentation for more information.

• Ensure that an Adyen Integration v2.0 gateway instance is in active use in your Zuora tenant.

Enable Adyen Apple Pay

Take the following steps to enable Adyen Apple Pay:

1. In your Zuora tenant, navigate to Settings > Payments > Payment Method.
2. Click Edit and then select Adyen Apple Pay.
3. Click Save. The Adyen Apple Pay payment method is then activated in your Zuora tenant.

Note that no update is required for your existing Adyen Integration v2.0 instance in Zuora to support Apple Pay.

Create a payment method

You can use the Create a payment method REST API operation to create an Adyen Apple Pay payment method. The following fields must be specified in the request:

• accountKey: Specify the customer account ID. This field is required unless the Orphan Payment Method feature is enabled.
• type: Specify AdyenApplePay.
• applePaymentData: Include payload with Apple Pay token or Apple payment data. This information should be stringified.

You can also pass the shopperEmail information to the gateway through any of the following methods:

• Use the email field in any of the following API operations:
  • Create a payment method
  • Create an account
  • Create an order
  • Create an order asynchronously
• Use the gatewayOptions field in the Create a payment method API operation.

If shopperEmail is not provided through either the email or gatewayOptions field, the shopperEmail field in the payment request is set to the BillTo personal email if it is available. If BillTo personal email is not specified, the shopperEmail field is set to the BillTo work email.

The following code is a sample request:

{
"accountKey": "2c92c0f97911f46a0179147510484b90",
"type": "AdyenApplePay",
"email": "testemail@test.com",
"applePaymentData": 
  "{\"data\":\"hM8GTBX0UVhoKmJ/DkneZfwLlH/utWfEueshybbTpuzlf5i1IwO1kvW32SlFW7TmyvU98gf2Pp1FeyFCh7F2atmstxQdonkeJgpIUV7eWW1wUNaOeND28J8YQsEkDhC3sMgOJoju7FHcXNwveq5fk94StFZozRSi08oAjTnTJko5F32aY/JNWr19GiwWBHZe2jkokryt0TEWKO5hm5oTxeLs1LBOoC2ezaR+p2jQb4ISN2aCgCNiX8605w5eYWk7UCTK3Axf/EuJT4vHe75OKghEmcQLxvFzTtEw33ly6Nj2RJX3+I5TbYLXOfiAO0XnsWdhguDrKogtI44HMFqlNCdt79G71tXwCwbXz0VJywEh1d57tbU5Y5f6pw8TrjjeAMt9sa2pHuHmMGDf\",\"signature\":\"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\",
    \"header\":
    {
      \"publicKeyHash\":\"vJeh5XAkv8SGX2JHswEbnCUPn01YHcQ6imAp+gP300w=\",
      \"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEVx9kP/eFM6MrP5sXKuzHT7f9Uhsc0Rox0FKvRpHIiqQ05EXYPsgBJZCEjOYlkviC2jDSvV6tEC8Kfq/z/GhrFA==\",
      \"transactionId\":\"7fd9ede5ea8c1d7a8985346c241a8933190a1acb408448c52ac27f7862f674ff\"
    },
    \"version\":\"EC_v1\"
  }"
}

You must ensure that the currency and authorization amount included in applePaymentData are the same as the ones configured in your Apple Pay payment form when Verification is enabled. Verification is required to return a recurringDetailReference that will be used in subsequent requests. In the example above, the currency is EUR and the authorization is 1.

In addition to the Create a payment method REST API operation, you can also use the following REST API operations to create an Apple Pay payment method together with other objects:

• Create an account
• Create an order
• Create an order asynchronously

Note that once an Adyen Apple Pay payment method is created, it cannot be edited. 

View and export Adyen Apple Pay payment method data 

After an Adyen Apple Pay payment method is successfully created, you can view this payment method from the customer account details page in the Zuora UI or the response of the API operations for retrieving payment methods.

All related information about Adyen Apple Pay payment methods can be exported using the Method Specific Data field for the Payment Method data source. If you are not familiar with Data Source Exports, see Create a Data Source Export for instructions.

To filter only specific information about Adyen Apple Pay payment methods, you can use several other Payment Method data source fields. The following table provides the mapping relationship between Zuora data source fields and Adyen Apple Pay fields.

Note that in the Credit Card Type field in the UI and the appleCardType field in the API response, Zuora stores the first 100 characters of paymentMethodVariant returned from Adyen.

Make payments with Adyen Apple Pay

After an Apple Pay payment method for Adyen has been added to a customer account, it can be used to make payments similar to using credit cards. You can use Adyen Apple Pay payment methods in all REST operations for processing payments, except for CRUD operations.

You can pass the shopperEmail information to the gateway through the gatewayOptions field in the Create a payment REST API operation. For more information about the logic of populating the shopperEmail field in the request, see Gateway Options fields supported by Adyen Integration v2.0.