Zuora Billing Integration

Setting up the Billing Integration is an essential step in provisioning PeakCommerce Production and Sandbox tenants. Zuora is one of the billing systems that PeakCommerce can integrate with. 

To get to the Billing Integrations page, navigate to Integrations > Billing. These settings can be managed by clicking the edit button at the bottom of the page. See the example below.

Follow the steps below to integrate the PeakCommerce platform with Salesforce.

Log in to Zuora with an admin account from the company in order to create an API Only user at the platform level. An API role must already be created. For more information on creating an API role, and setting up a new API user, view the Zuora article: Create an API User.

Click on the username in the top right corner and navigate to Setting > Administration > Manage Users. Click “add single-user” to start filling out the basic information. See the example below.

This page requires basic information to create the user. A description of each field can be found below in the order they appear on the New User page. 

• Tenant Id: This field is automatically populated. 

• Tenant Name: This is field is automatically populated. 

• First Name: Contact Zuora administrator for the appropriate name to assign. The name can be edited later. 

• Last Name: Contact Zuora administrator for the appropriate name to assign. The name can be edited later.

• Work Email: Contact Zuora administrator for the appropriate group email to assign.

• Login Name: Contact Zuora administrator for the appropriate name to assign. The login name cannot be changed after creating the user.

• Zuora Platform Role: This must be set to "API Only".

• Billing Role: Contact Zuora administrator for the appropriate role to assign. 

• Payments Role: Contact Zuora administrator for the appropriate role to assign.

• Finance Role: Contact Zuora administrator for the appropriate role to assign.

• Commerce Role: Contact Zuora administrator for the appropriate role to assign. 

• Reporting Role: Contact Zuora administrator for the appropriate role to assign. 

• Locals: This should be set to the companies specific region.

• Language: This should be set to a preferred language.

After filling in these fields click "save" at the bottom of the page. Go into the email used to create the user and wait for an activation email from Zuora.

Upon receiving the email, open the link provided in an Incognito window to set the password and create a security question. You can then close this window and go back to the Zuora admin. 

The information from the new user must be added to the Billing Integrations page on PeakCommerce. A description of these fields can be found in the order they appear.

Endpoint

For API Sandbox, the URL in this field should read: https://apisandbox.zuora.com/apps/services/a/52.0

For Central Sandbox, the URL in this field should read:
https://test.zuora.com/apps/services/a/52.0

For Production, the URL in this field should read: http://zuora.com/apps/services/a/52.0. 

Note: When provisioning PeakCommerce Production tenants, this field will prepoulate with the same URL as was entered here in Sandbox. Update it to the Zuora's Production URL. 

Username

Enter the Login name used to set up the API user in Zuora into the field. 

Password

Enter the password used to activate the API user set up in Zuora into the field. 

Tenant Id

The Tenant Id can be found in Zuora in the Basic Information of the API user that was just created. See the example below. 

Copy the Tenant Id and paste it into the field in PeakCommerce

API Security Key 1.0 and 2.0

These fields refer to the versions of Hosted Pages being used. The API Security Keys can be found in Zuora by clicking on the username in the upper right corner and navigating to Payments > Setup Hosted Pages. 

On the page, there are buttons that say “get hpm 2.0 key” and “get hpm 1.0 key”. See the example below. 

Clicking on the buttons will download text files containing the keys. Open the files to copy the keys one at a time and paste them into PeakCommerce ensuring there are no spaces. 

Zuora App URL

For API Sandbox, the URL in this field should read https://apisandbox.zuora.com.

For Central Sandbox, the URL in this field should read https://test.zuora.com.

For Production, the URL in this field should read https://zuora.com.

Note: When provisioning PeakCommerce Production tenants, this field will prepoulate with the same URL as was entered here in Sandbox. Update it to Zuora's Production URL.

Zuora Rest URL

For API Sandbox, the URL in this field should read https://rest.apisandbox.zuora.com. 

For Central Sandbox, the URL in this field should read https://rest.test.zuora.com. 

For Production, the URL in this field should read https://rest.zuora.com. 

Tip: When provisioning PeakCommerce Production tenants, this field will pre-populate with the same URL as was entered here in Sandbox. Update it to Zuora's Production URL. 

Client Id and Client Secret

The Client ID and Client Secret are created by creating an OAuth client on the API user in Zuora. This is used to authenticate to the Zuora Rest API. To create an OAuth pull up the new API user. Underneath the user's profile Basic Information there is a section for OAuth Clients. See the example below. 

In the OAuth Clients section, enter a name for the OAuth client and hit create at the bottom of the page. Zuora will display a one-time popup with the Client Id and Client Secret. This is the only time you will see these fields however, the Client Id and Secret can be regenerated if needed. Copy the Id and Secret and insert them into the fields in PeakCommerce.

After all these steps have been completed, the integration can be tested in PeakCommerce by adding a new product.

Navigate to Subscribe > Segments > Actions > View (on an existing segment) > Add Product.

When opening adding a new product, the products and rate plans from Zuora should appear in dropdown lists to choose from for the Product and Product Rate Plan fields.