Skip to main content

Batch Gateway Reconciliation overview

Zuora

Batch Gateway Reconciliation overview

  1. Last updated
  2. Save as PDF

What is Gateway Reconciliation

Gateway reconciliation is the process of verifying that the electronic payment and refund transactions processed in Zuora match the transactions reported by the gateway. For example, if Zuora processed 200 transactions through a gateway, you should see the same number of transactions on the gateway's reconciliation report, sometimes also called the settlement report.

A settlement report usually includes events from the following three stages of a payment's lifecycle:

  1. Processing event indicating that Zuora submitted the payment to the gateway.
  2. Settlement event indicating that the payment has been successfully debited from the payer and credited to the payee. For credit cards, settlement can take up to three business days. With some payment methods, like direct debit, it's possible that settlement fails.
  3. Post-settlement events are usually exceptions, like chargebacks for credit cards and reversals for other payment methods. These types of events indicate that the customer has taken an action through their bank that affects the payment.

How does Zuora Batch Gateway Reconciliation service work

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.

  • 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.

This feature is in Limited Availability. 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.

Zuora gateway integrations that support Batch Gateway Reconciliation

Batch Gateway reconciliation is currently supported by the following gateways.

If you have the Multi-entity feature enabled, you must apply for a merchant account for each entity. Use the corresponding merchant ID to configure the payment gateway instance for each entity.

Real-Time Reconciliation 

In addition to batch Gateway Reconciliation described in this article, Zuora also provides Real-Time Reconciliation. With Real-Time Reconciliation enabled, payment gateway can submit notifications to Zuora for various event types on gateway objects, and the corresponding records can be automatically updated in real-time. See Real-Time Reconciliation for more details.