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 or the API approach.
Payment Gateway Integration | Supported Approach |
---|---|
Adyen Integration v2.0 |
|
Braintree v2.0 | JavaScript SDK |
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 | Create an Apple Pay payment method REST API operation |
For information on setting up Apple Pay through Payment Form see Payment Form.
Set up Apple Pay through the JavaScript SDK approach
This section describes how to add Apple Pay to your checkout flow by integrating with the latest version of JavaScript SDK provided by Zuora. If you need guidance for the legacy version of the JavaScript SDK, see Set up Apple Pay with legacy version of Zuora JavaScript SDK.
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:
To integrate with Zuora's JavaScript SDK for Apple Pay setup, complete all of the following tasks:
- Ensure you complete prerequisite tasks before the integration.
- Register your domains with Apple Pay.
- Implement the client-side SDK integration.
- Implement the server-side API integration.
- Perform integration testing.
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.
This feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters.
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.
- Turn on the Payment Form feature in Zuora:
Submit a request at Zuora Global Support to turn on the Payment Form feature on your tenant. The JavaScript SDK integration utilizes the publishable key from the Payment Form feature for authentication. This integration supports embedding the Apple Pay button within an iframe hosted by Zuora. - Turn on the Payment Link feature and add your public business information:
- Follow the instructions in Enable payment features by yourself to turn on the Payment Link feature.
- Follow the instructions in Add public business information to invoice payment page to add the business name and web address of your company.
- 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.
- Download and unzip the following domain-verification file that will be used for domain registration with Apple Pay:
- Under the following path, host the uncompressed file from step 1 for each domain you want to use, naming it apple-developer-merchantid-domain-association. Ensure that the domain-verification file is accessible.
https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association
- 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:
- Click your username in the upper right and navigate to Settings > Payments > Setup Payment Page and Payment Link.
- Click the E-Wallets tab.
- 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.
- Click Add Domain.
- 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 client-side SDK integration
Step 1. Load zuora.js
Import the Zuora JavaScript client library to your page:
<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
- Copy the publishable key from Payment Form. In the Zuora UI, click your username in the upper right and navigate to Settings > Payments > Dynamic Hosted Payment Form. On the Publishable Keys tab, copy the key.
- Initialize an instance of the Zuora object with your publishable key.
- 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:
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:
buttonRadius string Default:
7px
The button corner radius in pixels, such as
10px
.buttonHeight string The button height in pixels, such as 30px
.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 must be provided when implementing the server-side API integration. See Implement server-side API integration to create payment session. - Mount the button component to the container.
- 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>
Implement server-side API integration to create payment session
In your server, make an API request to the Create a payment session endpoint. For details about constructing the API request and implementing payment flows, see Create a payment session in the API Reference.
Perform integration testing
In your client code, provide a valid callback for createPaymentSession
, which makes a call to your backend API to create a payment session.
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.
Process the payment
Zuora will handle the payment processing and complete the payment. You do not need to implement any integration for this.
View and export payment method data
After an Apple Pay payment method is successfully created, it is shown as a Credit Card payment method type in Zuora. You can retrieve this payment method through the UI, API, Data Source Export, and Data Query.
Set up Apple Pay through the API approach
- To implement Apple Pay integration on the following gateway integrations by using the Create an Apple Pay payment method REST API operation, see the Create an Apple Pay Payment Method API approach section:
- Chase Paymentech Orbital (Latest version)
- Chase Paymentech (Orbital) Gateway 7.0.1 Integration
- Checkout.com
- CyberSource, Payment API v2.0
- Vantiv (Now Worldpay) Gateway
- Stripe v2
- To implement Apple Pay integration on Adyen Integration v2.0 by using the Create a payment method API operation, see the Create a Payment Method API approach section.
Create an Apple Pay Payment Method API approach
This approach works for setting up Apple Pay on the following gateway integrations:
- Chase Paymentech Orbital (Latest version)
- Chase Paymentech (Orbital) Gateway 7.0.1 Integration
- Checkout.com
- CyberSource, Payment API v2.0
- Vantiv (Now Worldpay) Gateway
- Stripe v2
Prerequisites
Complete the following steps to configure Apple Pay:
- 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.
- 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.
- Generate the Apple Pay certificate and send it to Zuora:
- 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.
- On the Apple Pay website, upload the CSR file, and then download the payment processing certificate.
- Send the payment processing certificate back to Zuora Global Support together with your Apple Pay merchant ID.
- 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.
Create a Payment Method API approach
This approach works for setting up Apple Pay on Adyen Integration v2.0.
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:
- In your Zuora tenant, navigate to Settings > Payments > Payment Method.
- Click Edit and then select Adyen Apple Pay.
- 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
: SpecifyAdyenApplePay
.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: - 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:
Method and endpoint | POST https://apisandbox.zuora.com/apps/v1/payment-methods |
Request body |
{ "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:
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.
Data source field | Adyen Apple Pay field | Description |
---|---|---|
Method Reference Id | AppleGatewayToken | The recurringDetailReference returned from Adyen after a successful response. |
Sub-Type | AppleCardType | The brand or type of the card. For example, Visa and Mastercard. |
User Reference Id | AppleCardNumber | The last 4 digits of the DPAN returned from Adyen as the card summary. |
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.