Skip to main content

Set up the integration in the Zephr console

Zuora

Set up the integration in the Zephr console

  1. Last updated
  2. Save as PDF

In the Zephr console, take the following steps to set up the integration.

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.
  3. 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 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 you are using and scroll to the bottom of the page. And then create a Client credential by clicking Create. For more information, see the Manage OAuth 2.0 clients topic in the Zuora Knowledge Center.
    • The Zuora API URL field should be filled in with the API endpoint of your Zuora tenant. For a list of the available API endpoints, see Zuora Data Centers for more information.
  4. On the Customer Configuration tab, add the slugs for the First Name and Last Name user attributes you added in the Add user attributes section:
  5. On the Product Configuration tab, complete the following fields:
    • Leave the “Product IDs to be managed by Zuora Billing” section with an empty array (`[]`) for now. You need to specify the Zephr product IDs that will be mapped to the products in Zuora in the array later.
    • The “Courtesy grant duration” field allows you to control how much immediate access to content 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 ensure you allow enough time in the courtesy grant to ensure users have access to 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.
  6. On the Webhook Security tab, add the basic authentication details that 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.
  7. Back 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 showing up on the Billing extension card.

billing_extension_activated_mar23-1.png

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

Take the following steps to create Zephr products:

  1. Navigate to Products > Catalogue.
  2. 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.billing_extension_product_mar23-1-768x487.png
  3. Once you have created your products, you need to add the product IDs to the Zuora extension. Products 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, which was 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 forms”) for your features. However, 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 having selected the payment options. But note that an error would appear if some of the selected payment options are not available 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. These information can be retrieved on the Hosted Pages setting page in the Zuora console.
  • Navigate to Hosted Pages by clicking on 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, locate the page you want to use. You can retrieve the page ID by clicking the Show Page ID button. To retrieve Hosted Page URL, open the page you need and move down 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.

billing_extension_checkout_mar23.png

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