Skip to main content

Configure your Zuora tenant for the integration

Zuora

Configure your Zuora tenant for the integration

  1. Last updated
  2. Save as PDF

In the Zuora console, take the following steps to complete the needed configurations for the integration.

Step 1. Create a custom field on the Subscription object

From the user menu in the top right, navigate to Billing > Manage Custom Fields > Subscription Fields.

Click Add New Field, and then specify the following properties for the custom field:

  • Field Type: “Text”
  • Field Label: “Subscription Experience Product ID”
  • API Name: “SubscriptionExperienceProductID”
  • Length: 255

Click Save.

Zuora_CustomField_Mar23-1-768x343.png

Step 2. Create a Hosted Payment Page

  1. Use the user menu in the top right to navigate to Payments > Payment Method and click Edit. Add Credit Card to active and click Save.
  2. Use the user menu in the top right to navigate to Payments > Setup Payment Page and Payment Link.
  3. At the bottom of the page (in the Page List section), select Credit Card from the Type drop-down list, and then click Create New Hosted Page:Zuora_Create_hosted_page_mar23-768x376.png
  4. Specify the following properties for the new hosted page:
    • Page name: enter a name for the page
    • Hosted domain: the domain of the site for which you wish to add the payment page (e.g. “https://mydomain.com”)
    • Callback path: “/plugins/public/zuora-billing/callback”
    • Default Payment Gateway: select the payment gateway for the page
  5. Make sure the following page fields are selected. Note that Country and Email Address must be set to be “Returned in Response”.Zuora_hosted_page_field_mar23-768x413.png
  6. Click Generate and Save Page.

Step 3. Set up the Payment Processed and Cancel Subscription notifications

Set up the Payment Processed notification

  1. Use the user menu in the top right, navigate to Payments > Setup Profiles, Notifications and Email Templates.
  2. Scroll down the list of notifications until you reach Payment Processed. Click Edit and configure a callout notification with the following properties:
    • Basic Information: check the Active checkbox
    • Event Parameters: select Electronic for the Payment Type field
    • Delivery Options: check the Callout checkbox
    • Base URL: “https://<yourdomain>/plugins/public/zuora-billing/subscriptionCharged”
    • HTTP Method: POST
  3. Click Add Parameter, then specify the Parameter Name field as accountId and select Account.ID for the Parameter Value field. Note the lowercase “a” and lowercase “d” at the start and end of accountId.
  4. Callout Authentication: Check Username/Password, then specify the Username, Password and Domain fields. (You’ll also need to add these values to Zephr later; choose a strong password, for example a randomly generated UUIDv4.) Note: You can specify any string value for the Domain field. But you must use the same value here for all the notifications set up for the integration, and the same value must also be specified for the Realm field on the Zephr side later.
  5. Check the Enable Preemptive Authentication checkbox.
  6. Click Save.

(Optional) Set up the Cancel Subscription notification

  1. Use the user menu in the top right, navigate to Billing > Setup Profiles, Notifications and Email Templates.
  2. Scroll down the list until you find the Cancel Subscription notification (make sure it has “Related Event: Order Action Processed”). Click Edit And configure a callout notification with the following properties:
    • Basic Information: check the Active checkbox
    • Event Parameters > Type: select CancelSubscription
    • Delivery Options: check the Callout checkbox
    • Base URL: “https://<yourdomain>/plugins/public/zuora-billing/subscriptionCancel”
    • HTTP Method: POST
  3. Click Add Parameter, then specify the Parameter Name field as accountId and select Account.ID for the Parameter Value field. Note the lowercase “a” and lowercase “d” at the start and end of accountId.
  4. Callout Authentication: Check Username/Password, then specify the Username, Password and Domain fields (you’ll also need to add these values to Zephr later; choose a strong password, for example a randomly generated UUIDv4; these will be the same authentication values as above in the Payment Processed callout notification).
  5. Check the Enable Preemptive Authentication checkbox.
  6. Click Save.

Step 4. Create products

  1. Navigate to Product Catalog using the menu on the left sidebar.
  2. Create any products you need here. Pay attention to the following when creating products:
  • It is recommended to set “Billing Day” to “Subscription Start Day”.

  • The Rate Plan Charges must contain a `Processed Through Date` (Start Date) and a `Charged Through Date`(End Date). If the dates are unavailable, the Rate Plan Charged will be ignored, and no grants will be issued. To ensure the Rate Plan Charge contains these dates, you must set the Timing and Frequency of Charge > End Date field to Fixed period after the Charge is triggered when creating the charge.

For detailed instructions on how to create product rate plans and product rate plan charges in Zuora, see the Product Catalog section.