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

Navigate to Extension Studio > Object Manager in the left navigation menu. From the object list, click Subscription.

Click the Create icon create.png, and then specify the following properties for the custom field:

  • Name: “Subscription Experience Product ID”
  • API Name: “SubscriptionExperienceProductID__c”
  • Field Type: “Text”
  • Max Length: 255

Click Save.

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. Navigate to Extension Studio > Events & Notifications in the left navigation menu.
  2. Locate the notification for the Payment Processed event and click the Edit icon edit.png. The Edit Notification Definition page opens.
  3. Update the following properties:
    • Basic Information: Toggle to enable the Active field.
    • System Filters: Select Electronic from the Payment Type drop-down list.
    • Delivery Options: Select the checkbox for the Callout delivery type and select a callout template from the dropdown list.
  4. Click Save.
  5. Click the Callout Templates tab and locate the callout template for the Payment Processed event you selected in step 3.
  6. Click Edit.
  7. Update the following information:
    • HTTP Method: POST
    • Request URL: “https://<yourdomain>/plugins/public/zuora-billing/subscriptionCharged”
    • Request Body: 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.
    • Request Authentication:
      • Select Username/Password from the Authentication Type list, 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.
      • Check the Enable Preemptive Authentication checkbox.
  8. Click Save.

See Create a callout template section for instructions on entering the other field values.

(Optional) Set up the Cancel Subscription notification

  1. Navigate to Extension Studio > Events & Notifications in the left navigation menu.
  2. Locate the notification for the  Cancel Subscription notification (make sure it has “Related Event: Order Action Processed”), and click the Edit icon edit.png. The Edit Notification Definition page opens.
  3. Update the following properties:
    • Basic Information: Toggle to enable the Active field.
    • Event Parameters > Type: Select CancelSubscription.
    • Delivery Options: Select the checkbox for the Callout delivery type and select a callout template from the dropdown list.
  4. Click Save.
  5. Click the Callout Templates tab and locate the callout template for the Cancel Subscription event you selected in step 3.
  6. Click Edit.
  7. Update the following information:
    • HTTP Method: POST
    • Request URL: “https://<yourdomain>/plugins/public/zuora-billing/subscriptionCancel”
    • Request Body: 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.
    • Request Authentication:
      • Select Username/Password from the Authentication Type list, 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.
      • Check the Enable Preemptive Authentication checkbox.
  8. Click Save.

See Create a callout template section for instructions on entering the other field values.

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.