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

Batch Gateway Reconciliation overview

How does Zuora Batch Gateway Reconciliation service work

Zuora's Batch Gateway Reconciliation service processes daily settlement reports from gateways, matching events with transactions to update gateway states and log actions. It supports multiple gateway instances and provides detailed reconciliation features.

Most gateways produce settlement reports on a daily basis. Zuora follows the schedule appropriate for each gateway, which is usually daily, and retrieves the appropriate gateway reconciliation report for processing in a job. Within a reconciliation job, every record in the report is parsed into an event and matched with the corresponding Zuora transaction. Zuora then takes the appropriate action based on the event information received and logs it.

Occasionally, more than one job might occur in a single day, often due to Zuora releases. When a job is running and a Zuora release occurs, the job is stopped. After the release is completed, the interrupted Gateway Reconciliation job is resumed with a new job.

Zuora Gateway Reconciliation feature supports retrieval and recording of gateway's payment processing, settlement, and post-settlement events, to aid in the gateway reconciliation efforts. In Zuora, the Gateway Reconciliation service processes data for the gateway integration type configured with Gateway Reconciliation. If you have multiple gateway instances of the same gateway integration type, reconciliation information of all these gateway instances will be processed and logged.

Note:

  • The Gateway Reconciliation job only reconciles payment or refund transactions that occurred within the past year.

  • Gateway Reconciliation only applies to the gateway state of the payment or refund transaction. Cash Reconciliation is the actual financial information of the amount that was settled, the fees charged, and potential currency exchange performed. Cash reconciliation is not supported at this time. Zuora does not support reconciliation of refunds that are rejected. Only settled refunds are supported for gateway reconciliation.

  • Support details of gateway reconciliation vary for different gateways. For more information, see the specific article for each gateway listed in Zuora gateway integrations that support Gateway Reconciliation .

The following table lists the event types and the actions taken for each event:

Event Type

Action

Successful Settlement

Zuora updates the Gateway State to "Settled" and the Settled On date field of a Payment transaction.

Settlement Error

  • Zuora updates the Gateway State to "Failed to Settle" on the Payment transaction

  • Zuora creates an external refund with the reason code set to "Payment Rejection" if the code is active in the Reason Codes list . Otherwise, Zuora creates an external refund with the reason code set to the default reason code in the list.

  • Refunds created for payments previously applied to a future invoice will have the same refund date as the invoice date. This is one reason why the Creation Date and Refund Date for a refund differ.

  • If the Support refunding payments from the credit balance with Gateway Reconciliation setting is enabled, a credit balance refund will be created. See Refund payments with credit balance in gateway reconciliation for more information.

  • Zuora updates Failed Payment count on the corresponding Payment Method

Post-Settlement Exception

Optionally, Zuora creates an external refund with the reason code set to "Payment Reversal" if the code is active in the Reason Codes list . Otherwise, Zuora creates an external refund with the reason code set to the default reason code in the list.

Zuora provides a feature to disable payment reversal in Gateway Reconciliation chargeback events. With this feature enabled, Zuora will not create an External Refund when a Post-Settlement Exception occurs, and you need to use your own logic to process the settlement events. By default, this feature is disabled.

Note:

This feature is in the Early Adopter phase. If you want to have access to the feature, submit a request at Zuora Global Support .

Unknown Transaction

Zuora just logs the event and does not take any action.

Unmapped Event

Zuora just logs the event and does not take any action.

You can also use the Payment Gateway Reconciliation REST API operations to reconcile payments and refunds.

You can use the Retrieve a payment API operation or the Payment Data Source Export to retrieve the value of the Gateway State field. For more information about the Gateway State field, see Electronic Payment Processing .

Last updated: November 17, 2025