Integration setup in Zephr console

Step 1. Add user attributes

1. Navigate to Identity > User Attributes.
2. Add attributes for First Name and Last Name, and make sure these are both of type Text.

Step 2. Configure and activate the Billing extension

1. Navigate to Settings > Extensions.
2. Select the Billing extension. The following screen is displayed:
   
3. Select the required environment, such as Live Environment. The selected environment screen is displayed as shown in the following image:
   
4. On the Zuora API tab, enter a Zuora Client ID, Client Secret and the Zuora API URL for the environment you want to integrate.
   • You can create a Zuora client ID and client secret code in the Zuora console by clicking on your profile icon in the top right corner and then navigating to Administration > Manage Users. On the Users page, open the details page of the Zuora user and scroll to the bottom of the page. You can then create a client credential by clicking Create. For more information, see the Manage OAuth 2.0 clients topic in the Zuora Knowledge Center.
   • You can enter the API endpoint of your Zuora tenant in the Zuora API URL field. For a list of the available API endpoints, see Zuora Data Centers for more information.
5. On the Customer Configuration tab, add the slugs for the first and last name user attributes you added in the Add user attributes section.
6. On the Product Configuration tab, complete the following fields:
   • You can leave the Product IDs to be managed by Zuora Billing section with an empty array (`[]`). You need to specify the Zephr product IDs that will be mapped to the products in Zuora in the array.
   • The Courtesy grant duration field allows you to control the access to the content that users receive. Zephr will add a full product grant for the billing period once a callout notification is received that card details have been successfully charged. This process can take up to 60 mins. If you have an alternative arrangement (e.g. you only run billing and charge cards overnight), please allow enough time in the courtesy grant to ensure users can access content until their details are charged.
   • If you wish to charge end users’ cards as soon as they subscribe, check the Run billing and collect payment immediately option.
7. On the Webhook Security tab, add the basic authentication details you chose when setting up the Callout Notifications in the Zuora console.
   Note: For the Realm field, you must specify the same value that is specified for the Domain field in Zuora. 
8. On the Billing extension main options page, click the Use as Payment Provider button to activate the extension.

The extension is successfully activated if you see the Active icon on the Billing extension card.

You can now move on to configure your products in Zephr.

Step 3. Create Zephr products

With Zuora Billing enabled, each payment option in Zephr maps to a product rate plan in Zuora. The following information forms the title of a Zephr payment option:

• Zuora product name
• Zuora product rate plan name
• Zuora product rate plan ID

To create Zephr products, perform the following:

1. Navigate to Products > Catalogue. 
2. Click Add a Product and create the Zephr products you need. The products may well match 1:1 with your Zuora products. In each product, be sure to add the relevant Zephr features. To add rate plans as payment options, click Add a Payment Option; you can either start typing in the search box to find the relevant rate plan or browse an alphabetical list.
   
3. Once you have created your products, you must add the product IDs to the Zuora extension. Product IDs are the slugs of your products. Navigate back to the Zephr Product Grant Configuration setting page in the Zuora extension, and then add the product IDs under Zephr Products IDs as an array of strings. For example, if you have two product IDs – “gold” and “silver”, specify the following as the value:
   [“gold”, “silver”].

Step 4. Create payment form pages

After you have mapped your Zephr products with the products created in Zuora, you can start building paywalls for your features. To build the paywall, you need to use the Payment Form, previously known as Frictionless Checkout Form.

Important Note: You can follow the general flow documented in Payment Form to create payment forms (previously known as Frictionless Checkout Form) for your features. However, the payment form is customised for the Zuora Billing integration. Make sure that you go through the following required configurations that are unique to the Zuora Billing integration:

• On the Products & Payment Plans tab, you can specify the currency in which the payment options are available. This allows you to set up payment forms that can be used for different regions. 
• Note that after you have selected a currency, you can only choose to add payment options that are available in that currency. You can change the currency to another one after selecting the payment options. However, an error would appear if some of the selected payment options are unavailable in the newly selected currency.
• When adding a payment option, an auto-generated description will be filled into the Description field. The content is retrieved from the corresponding Zuora product rate plan. You can update the description as needed.
• Under the Zuora Hosted Payment Page section on the Payment tab, you must embed a Zuora Hosted Payment Page into the payment form. You need to enter the Payment Page ID and Hosted Page URL to embed the Hosted Payment Page. This information can be retrieved on the Hosted Pages setting page in the Zuora console.
• Navigate to Hosted Pages by clicking your profile icon in the top right corner and then clicking Payments > Setup Payment Page and Payment Link. Scroll down to the Page List section to locate the page you want to use. You can retrieve the page ID by clicking the Show Page ID button. To retrieve the Hosted Page URL, open the page you need and move to the Implementation Details section.

In addition, when your end users use the payment form to checkout, all the charges are listed in the Subscription Details section, as shown in the example below. The amounts are calculated by Zuora.

The Subscription Information section of the end user’s Preference Centre page displays details of the product rate plans purchased by the users.