home

Zuora Payments

Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableZuora AIRelease NotesBasicsEntitlementsSupport and policies
Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableZuora AIRelease NotesBasicsEntitlementsSupport and policies

Welcome to Zuora Product Documentation

Explore our rich library of product information

Show Contents

Show Page Sections

thumbnailZuora Payments

Upgrade to Modernized Zuora Payments

Upgrade guidance

Learn how to upgrade to Modernized Zuora Payments to take advantage of a modern and no-code experience for managing your payment forms.

Upgrading to Modernized Zuora Payments delivers an optimized checkout experience while reducing operational overhead. The Modernized Zuora Payments:

  • Is PCI-compliant.

  • Can be easily customized with no code.

  • Dynamically displays payment methods based on region, order amount, currency, and custom metadata.

  • Inherently supports payment gateway routing.

Once you have upgraded to Modernized Zuora Payments, several UI and functional changes will occur. See Functional changes in Modernized Zuora Payments.

Upgrade considerations

Before you upgrade, review the following behaviors:

  • By default, the Checkout instance uses the default payment gateway to submit transactions until each payment method's route has been updated to not utilize a Metadata condition with a static connection-id assigned.

  • By default, the payment form in Checkout Builder submits transactions through the default payment gateway. To change this routing, you must update each payment method's route so it no longer uses a Metadata condition with a static connection I.

  • If a customer account has a default gateway, that gateway takes precedence over the tenant default gateway.

  • Fallback gateway handling does not support transactions that go through the 3DS2 flow.

  • Your existing Payment Pages 2.0 and Hosted Payment Forms experiences will remain the same until you actively choose to upgrade them.

  • Each legacy HPF maps to one Checkout instance. Each HPM page set consolidates into one Checkout instance that holds all its payment methods.

  • It is recommended to move to the Payment Form experience. As part of this migration, combine your existing payment pages into one payment form.

  • If you want to keep Payment Pages 2.0, you can use a single payment page that displays the full contents of the new Checkout instance. If you prefer multiple checkouts, you must use the Payment Form process instead.

Upgrade paths

Functional changes in Modernized Zuora Payments

The following table lists the function and UI changes after upgrading to Modernized Zuora Payments.

Functional Area

Zuora Payments

Modernized Zuora Payments

Navigation & UI

Provides standard navigation options: Overview, Payments, Payment Runs, Refunds, Payment Methods, Payment Method Updater, Gateway Reconciliation

Retains all standard options and adds top-level navigation for Connections, Routing, and Checkout.

Payment gateway integration

Configured via Payments Settings > Setup Payment Gateways.

Configured via the Connections page

Payment method setup

Configured via Payments Settings > Payment Method

Configured via the Connections page.

Payment Form

Managed via Payments Settings > Setup Payment Forms and Payment Links

Transitions to read-only status.

You can continue to view the legacy form list, but can no longer edit any legacy payment forms.

Payment Pages 2.0

Managed via Payments Settings > Setup Payment Pages

Transitions to read-only status.

You can continue to view the legacy page list, but can no longer edit any legacy payment pages.

Hosted payment form creation

Can be created via Payment Pages 2.0 or Payment Form

Created through Checkout Builder on the Checkout page.

Security configuration

Security settings for Payment Pages 2.0 (Security keys, Rate limiting, reCAPTCHA, Raw gateway info, and Advanced configuration) are available in Payments Settings > Setup Payment Pages.

Equivalent security settings are available on the Checkout page

Payment gateway routing

Supported through the Payment Gateway Routing feature.

Routing rules are configured through Payments Settings > Setup Payment Gateway > Payment Gateway Routing.

Enabled natively by default. Routing rules are configured on the Routing page.

Performance monitoring

Monitored via the standard dashboard within the Overview section.

Monitored via enhanced Insights dashboards.

Account Updater service

Supported by the feature. The support is gateway specific.

Supported via the feature, which is centrally managed by Zuora and is processor-agnostic .

Note that the payment methods tokenized through Modernized Zuora Payments are updated exclusively via Card Account Updater and cannot be processed by existing PMU workflows.

Reconciliation

Reconciliation setup is separate from the payment gateway configuration and varies by provider.

Configured as an integral part of the PSP connection, ensuring a unified setup experience.

Migrate from Payment Pages 2.0 based flow

  • Review Feature comparison between Zuora Payments and Modernized Zuora Payments.

  • Identify the payment pages that you currently use.

  • Document whether each flow creates a payment method, processes a one-time payment, or saves a payment method for recurring payments.

  • Review your existing hosted page configuration, including page fields, callback behavior, and CSS customization.

Payment Pages 2.0 configurations include custom CSS, scripting, prepopulated fields, and custom business logic. You can migrate these configurations to Checkout Builder in Modernized Zuora Payments. After the upgrade, your existing Payment Pages 2.0 list becomes read-only, and a persistent banner directs you to Checkout Builder.

This guide explains how to migrate from Payment Pages 2.0 to the Modernized Zuora Payments experience.

  1. Replace the ID of your primary payment page with the new Orchestration ID displayed on the UI.
    1. In the left navigation pane, navigate to Zuora Payments > Checkout.
    2. Click Implementation Guide.
    3. Click the Payment Page tab.
    4. Copy the orchestration ID in Step 1, and replace the old ID with it on your payment page.
    5. Hide any other legacy payment pages on the same checkout URL.
  2. Configure the return URL behavior using the values from your existing Payment Pages 2.0 configuration.
    1. In the Hosted Domain field, enter the domain from which your payment page is served. This is also the domain where your callback page resides, for example, https://www.domain.com.
    2. In the Callback Path field, enter the path where the callback page resides. Zuora appends this path to the Hosted Domain value to construct the full callback URL. For example, if the full callback URL is https://www.domain.com/callback, the Hosted Domain is https://www.domain.com and the Callback Path is /callback.
  3. Download the security key from the UI, and update the security keys in your existing Payment Pages 2.0 integration.
  4. Remove all legacy customizations from the payment page, including custom JavaScript validations, pre-populated field values, and custom CSS styling. For more detailed information on where to find these details, see Payment Pages 2.0 implementation guide.
  5. Test your migration by running a safe test in Sandbox to verify the setup, and launch.
  6. After you have validated the migration in Sandbox, make the same updates in your Production tenant to roll out the changes in Production.

Migrate from Payment Form based flow

If you currently use Payment Form, Zuora automatically converts your existing payment forms into new Checkout instances within Checkout Builder. Each existing form becomes a unique Checkout instance, retaining its original Payment Form number. These updates will not appear on your webpage until you click Publish for each form in Checkout Builder.

  1. Navigate to Zuora App Settings > Payments > Setup Payment Forms and Payment Links.

    This page lists all available payment forms in a table.

  2. Open the payment form that you want to migrate.
  3. For the payment form that you want to migrate, click Connect.

    Zuora creates a Checkout instance from the legacy form. The instance is not live.

  4. Optional: Edit the Checkout instance in Checkout Builder.
  5. Click Publish.

    Publishing saves the configuration for users of the form. It does not send live traffic.

  6. Click Upgrade, then confirm the upgrade.

After the upgrade, live traffic from the hosted payment form is migrated to Checkout Builder.

You can monitor traffic in the Insights dashboard.

Overview
Payments
Standard

Last updated: October 31, 2026