home

Zuora Payments

Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies
Zuora BillingZuora PaymentsZuora PlatformZuora CPQZephrZuora RevenueAccounts ReceivableRelease NotesBasicsEntitlementsSupport and policies

Welcome to Zuora Product Documentation

Explore our rich library of product information

Show Contents

thumbnailZuora Payments

Define and set up payment methods

Enable the support for Plaid account validation solution

This task explains how to enable and use Plaid's Auth and Balance products in Zuora for ACH transactions, including setup, authentication, and balance check flows.

This article describes Zuora's support for Plaid Auth and Balance products, and how to enable them in Zuora.

Support for Plaid Auth and Balance products can be requested through the Specialized Payment Connections service at an additional cost.

Plaid offers Auth and Balance products to streamline bank account validation in the payment flow. Auth authenticates account details before sending requests to the gateway, while Balance checks the real-time account balance before transactions. Currently, these Plaid products are supported for ACH transactions in Zuora.

To use the Plaid Auth and Balance products in Zuora, you must first enable them in both Plaid and Zuora. Once enabled, the following flows apply to the ACH transactions:

  • Authentication flow If Plaid Auth is enabled, you can implement a Payment Page 2.0 to add ACH payment methods in Zuora through the Plaid Link flow. The Plaid Link UI is displayed in the iFrame of the hosted payment page. The bank account information, routing number, and access token are returned and saved in Zuora.

  • Balance check flow If Plaid Balance is enabled, one-time and recurring payments made with the ACH payment methods that were created through the Plaid Link flow are processed through the Balance flow by using the access token. The account balance is checked before transactions.

The following procedure describes the end-user experience flow:

Zuora also supports the Plaid update mode to handle scenarios where your customers' bank credentials change. When this happens, the Plaid access token linked to the payment method is deactivated. If Zuora attempts to call the Plaid API for this payment method before the payment is made, the transaction fails, and a notification is logged in the Payment Transaction Log with the following details:

  • Gateway = 'Plaid'

  • GatewayResponseCode = 'ITEM_LOGIN_REQUIRED'

Based on this notification, you can implement custom logic to prompt your customers to re-authenticate their credentials. The following two scenarios may occur in the update mode:

  • If your customer's account is with a non-OAuth bank, they re-authenticate by entering their new credentials.

  • If your customer's account is with an OAuth bank, an additional account selection page is displayed:

    • If the customer selects the same payment method as before the credentials expired, the new credentials are authenticated, and the access token is re-activated for the existing payment method.

    • If the customer selects a different payment method, Zuora creates a new payment method. If the original payment method was the default, the new one becomes the default. Otherwise, it remains non-default. The previous payment method is deleted from the customer's account.

To enable the support for Plaid Auth and Balance, complete the following steps:

Setting up notifications allows you to proactively address issues that might impact payment processing. For example, if a bank account balance is insufficient, you can inform your customers to take corrective action, ensuring the next payment attempt succeeds. Similarly, if customer credentials have expired, you can notify the customer to re-authenticate before the next scheduled payment.

To receive notifications for bank account authentication and balance check events, complete the following steps:

  1. Your customer selects ACH from the hosted payment page implemented through Zuora Payment Pages 2.0. The Plaid Link page is displayed.
  2. Your customer selects a bank. A dialog presenting the partnership with Plaid is displayed.
  3. Your customer logs in to Plaid using bank credentials by following a wizard. A list of bank accounts is displayed.
  4. Your customer selects an account. A success message indicates that the selected bank account is successfully connected to the Plaid account. At the back end, a payment method is created, and an access token is generated and saved in Zuora.
  5. The payment transactions are made on schedule if the account has sufficient balance.
  6. Contact Plaid and get a Plaid account.
  7. In the Plaid dashboard, complete the following configurations:
    1. Enable Plaid Auth and Balance.
    2. Customize Link UI according to Plaid's instructions . When configuring Account Select , select Enable for one account as you can select only one payment method on Zuora's hosted payment page to process checkout.
  8. In Zuora, enable the support for the Plaid account validation solution on your tenant.
    1. Click your username in the upper right and navigate to Settings > Payments > Account Validations .
    2. On the Account Validations page, select the Enable Account Validation field. Enabling this field will also enable real-time reconciliation .
    3. In the Service Provider field, select Plaid .
    4. In the Client Name field, enter your company name that will be displayed in the following UI label on the Plaid Link page: <Client_Name> uses Plaid to connect your account
    5. In the Client ID and Client Secret fields, enter your Plaid credentials.
    6. In the feature enablement section, enable Plaid Auth, Plaid Balance Check, or both.
    7. If Plaid Balance Check is enabled, you can configure Sufficient Balance Multiplier , which defines the condition for processing payments if the available balance information is not returned by Plaid: Current Balance >= N times of the payment amount (where N is the value specified in Sufficient Balance Multiplier ) You can specify a value from 1 to 10, with up to two decimal places. To ensure sufficient funds and reduce the risk of payment failures due to insufficient balance, Sufficient Balance Multiplier between 3 and 5 is recommended as a best practice.
    8. Click Save .
  9. In Zuora, set up an ACH Payment Page 2.0. When configuring the hosted payment page, select Enable Account Validation for this specific ACH HPM Page in the Account Validations section. With this setting selected, the Auth flow is applied to the payment method creation. For detailed instructions on setting up Payment Pages 2.0, see Configure Bank Transfer type Payment Pages 2.0 .
  10. Define a custom event. Configure the related fields as described in the following table: For detailed instructions, see Manage custom events and custom scheduled events .

    Field

    Authentication

    Balance check

    Base Object

    PaymentTransactionLog

    PaymentTransactionLog

    Set Conditions

    PaymentTransactionLog.Gateway == 'Plaid'

    AND

    PaymentTransactionLog.GatewayResponseCode == <Plaid_error_code>

    For the available Plaid error codes, see Plaid's document .

    PaymentTransactionLog.GatewayResponseCode == 'Plaid_InSufficientFunds'

  11. Add a new callout or email template for the notification. In the Related Event field, select the custom event created in step 1. For detailed instructions, see Manage email and callout templates .
  12. Add a new notification. In the Related Event field, select the custom event created in step 1. For detailed instructions, see Manage Notifications .

To prevent payment failures and achieve better cost efficiency, we have now included support for reviewing whether your payment methods are verified by Plaid. Additionally, you can also verify the status of the tokens linked to the Plaid payment methods.

If you have enabled Plaid ACH validation, webhooks are automatically enabled for your tenant.

The status of their corresponding access tokens is available in the Account verification service and Account verification status fields. The status available on these fields will help merchants take preventive measures.

These fields are added to the ‘List payment methods of an account ’ and ‘Retrieve a payment method ’ APIs.If the payment method is Plaid verified, Zuora will populate one of the following statuses of the access token linked to the payment method:

  • Active

  • Expired

  • Expiring

  • InActive

  • Null

Account verification service populates the following values:

  • Plaid - If the payment method was verified by Plaid.

  • Null - If the payment method was not verified.

  • To export data about Plaid account validation, use Data Source Export or Data Query on the Payment Method Transaction Log object.

  • If you want to manually implement the integration with Zuora's support for Plaid Balance, you can use the Retrieve the balance of a bank account API operation.

Last updated: December 3, 2025