Learn how to configure and activate the Billing extension by navigating through settings, selecting the Billing extension, entering necessary credentials, and setting up product and subscription configurations.

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.
   Note: To access the Zuora Payment Form Publishable Key field, the feature flag, feature.dynamicHostedPaymentForms.enabled, must be enabled. If it's not, you can contact Zuora Support to have this field enabled.
   1. 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.
   2. 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.
   3. You can enter the publishable key from Zuora Billing in the Zuora Payment Form Publishable Key field to integrate and display your custom payment form in Zephr. Once integrated, you can use the payment form directly on a Zephr payment page ( Delivery > Component Library) and subsequently on your website.
5. On the Customer Configuration tab, complete the following fields:
   1. Add the slugs for the first and last name user attributes you added in the Add user attributes section.
   2. Enter the CRM system key, for example, from Salesforce or another external CRM in the CRM Foreign System Key field. Once this key is configured and saved, any new subscribers using the Zuora Billing payment provider will automatically have their crm_id set in their Zuora Billing Account. This crm_id links the Zephr subscriber profile with the external CRM record, enabling streamlined identity and account management.
      Zephr pulls billing information from Zuora at both the account and subscription levels, depending on the context:

      • Account-level data is used to sync user information such as custom fields, CRM ID, and account name.
      • Subscription-level data is used to determine what the customer currently has access to in Zephr, including new subscriptions, subscription status, any changes that result in access being granted or revoked, and so on.
      • Set the communication profile for your site. For information, see Communication profiles.
        Note: To ensure that any end-user experience orchestrated by Zephr using CRM ID, subscription ID, or custom fields functions correctly, this configuration must be completed.
6. On the Product Configuration tab, complete the following fields:
   1. 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.
   2. 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.
   3. Run billing and collect payment immediately - Enable this setting if you wish to charge end users’ cards as soon as they subscribe.
   4. Use Zuora Billing Products V2 API - Enable this setting only if you are integrating directly with the Zuora Billing Products V2 API. Do not activate this option if you are using Zephr API forms, as it may lead to compatibility issues.
   5. Use charge start & end dates to sync grants for canceled subscriptions (standard behaviour is to use processed and invoiced through dates) - Enable this setting to allow Zephr to sync user grants based on the charge start and end dates, instead of the default processed through and invoiced through dates. When enabled, the grants for canceled subscriptions will retain the original start date and correctly reflect the subscription’s end date. Previously, canceled grants displayed a new start date, making it difficult to track the original subscription period in the Zephr console.
   6. Force all change subscription actions to be effective at end of billing period - Enable this setting to control the timing of subscription changes by forcing all changes, such as upgrades or downgrades, to take effect only at the end of the current billing period. By default, Zephr applies these changes immediately and prorates any price differences on the next invoice. This new option helps maintain consistent billing behavior and can be useful for businesses that prefer changes to align with billing cycles.
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. Click the Payment Configuration tab and define your custom overrides using a JSON structure. This helps you override the default payment gateway on a per-site basis, providing greater flexibility for multi-site setups. You can specify accepted payment methods for each site by supplying a Gateway ID from your Zuora Billing tenant. If no override is provided, Zephr will default to the billing tenant’s standard gateway configuration. These overrides support a wide range of use cases:
   • Assign specific payment gateways to individual sites and payment methods.
   • Use dedicated gateways for select payment types, for example, PayPal, Google Pay.
   • Customize gateway assignments for only a subset of sites, for example, Site 2, Site 4, and Site 7.
   Sample:

   {
     "site1": {
       "CreditCard": "gateway_id_1",
       "PayPal": "gateway_id_2"
     },
     "site2": {
       "GooglePay": "gateway_id_3"
     }
   }

   Where;

   • site1, site2: Site identifiers within Zephr
   • CreditCard, PayPal, GooglePay: Supported payment methods
   • gateway_id_x: Corresponding gateway ID in your Zuora Billing environment. The Gateway ID must come from your Zuora Billing tenant.
     Note:

     • You can configure overrides for any combination of site and payment method. All unspecified combinations fall back to the tenant's default gateway.
     • Only payment methods supported by Zuora Hosted Payment Pages (HPM) or Dynamic Payment Pages (DPM) are supported. For unsupported methods (like ACH), you would need to build a custom integration.
9. Click the Subscription Management tab and enable self-service subscription actions. This is done by exposing an authenticated endpoint that integrates with the Zuora Orders API. Based on your configuration, this enables you to perform key subscription actions directly from the front end. The following order actions can be supported (depending on your configuration and implementation):
   • Create Subscription
   • Terms & Conditions
   • Add Product
   • Update Product
   • Remove Product
   • Renew Subscription
   • Cancel Subscription
   • Owner Transfer
   • Suspend / Resume
   • Change Plan
10. On the Subscription Management tab, complete the following fields:
    1. Select the Subscription Management checkbox.
    2. Select the required actions from the list.
    3. Click Done .
    4. Build or configure front-end UI components, such as buttons, forms, to call the Zephr API securely, using an authenticated user session.
       Note:

       • If no frontend integration is done, your users won't see or interact with any of these actions, even though they're technically enabled.
       • Enabling the Subscription Management checkbox in Zephr exposes a secure HTTP endpoint (/subscriptions/{subscriptionId}/manage) that allows your developers to build custom components or integrations forendusers to perform these actions from the front-end.
11. 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.