Skip to main content

Gateway Reconciliation


Gateway Reconciliation

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.

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.

  • 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, refer to the specific article for each gateway listed in the following Configuring Gateway Reconciliation section.

How Does Gateway Reconciliation 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. 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 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".

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. See the API Reference for details.

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.

Configuring Gateway Reconciliation

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.

Gateway reconciliation is currently supported by the following gateways. 

Enable gateway reconciliation

To use gateway reconciliation, select the Enable gateway reconciliation check box on the configuration page for the preceding gateways. Ensure that you have enabled the "Issue External Refund" payments permission, and the "Unapply Payment" payments permission if the Invoice Settlement feature is enabled in your tenant. Contact your tenant administrator to update your user role or corresponding permissions.

Refund payments with credit balance during gateway reconciliation

A setting called Support refunding payments from the credit balance with Gateway Reconciliation is available in Payments settings. If this feature is enabled, payments with an available credit balance amount can be refunded by using the credit balance during gateway reconciliation. This feature is only available when Invoice Settlement is disabled.

For more information about how to enable this feature, see Refund payments with credit balance in gateway reconciliation.

Configure how to handle refund rejected events

You can set the refund to "Rejected" through the "Reconcile Refund" API operation. If you specify reject for the action field, the subsequent actions of handling the refund rejected events take place according to the Gateway Reconciliation Configuration settings. In Zuora UI, navigate to Settings > PaymentsGateway Reconciliation Configuration, and then click the option for your needs. 

The following options are available:

  • Update the Refund gateway reconciliation fields only

    Default option. The gateway reconciliation fields will be updated.

  • Update the Refund gateway reconciliation fields and reverse the Refund

    The gateway reconciliation fields will be updated, and the following objects will be created:

    • If Invoice Settlement is not enabled, a new external overpayment will be created, in the case of a failed refund generated from a payment or credit balance.
    • If Invoice Settlement is enabled, a new external unapplied payment will be created, in the case of a failed refund generated from a payment.

      Note: In the case of a failed refund generated from a credit memo, Zuora will only update the gateway reconciliation fields. The new credit memo will not be created.

Viewing a Gateway Reconciliation Job

Zuora strongly recommends you to enable the Gateway Reconciliation Job Completion | Reconciliation Completed notification when you are using the Gateway Reconciliation feature. You will get notified when a Gateway Reconciliation job is completed or encounters an error. See Edit a Notification for more information.

  1. Navigate to Payments and select the Gateway Reconciliation.

The Gateway Reconciliation page lists the following information:

Column Name Description
Job Number The number assigned to the job for a particular reconciliation period.
Period Start This is the earliest date for which reconciliation events are expected for this job.
Period End This is the latest date for which reconciliation events are expected for this job.
Gateway Name The name of the gateway for which the source information will be retrieved.
Source Name The source from which the reconciliation report information will be retrieved. For example, the file name of the gateway settlement report.

The status of the reconciliation job.

  • Processing -- The job is processing.
  • Completed -- The job has completed and the report was successfully processed.
  • Error -- The job failed due to an error. The job details page provides additional information.
Last Attempt On The last time the system attempted to retrieve source information from the gateway.
Completed On The time indicating when the job completed.
  1. Click on the Job Number from the Gateway Reconciliation page to view the job details.

The gateway reconciliation job detail page provides the following information:

Basic Information
Job Field Description
Status The status of the reconciliation job.
Creation Date Time when the job was created.
Period Start The period of time in which reconciliation started for this particular job.
Period End The period of time in which reconciliation ended for this particular job.
Gateway Type The type of gateway used. 
Gateway Name The name of the gateway from which the source information will be retrieved.
Attempt History
Job Field Description
Attempt The number times the job has been submitted. If the initial attempt fails, the system will not retry automatically. The retrieval can be retried manually. 
Start Date Date when the attempt has started.
End Date Date when the attempt ended.
Source Name The name of the reconciliation report that is being retrieved.

The result of the attempt.

  • Succeeded
  • Failed - See the Reason field for more details.
Reason Only provided when the attempt fails, giving the reason for the failure.

Recovering from a failed Gateway Reconciliation Job

If the initial attempt to retrieve a gateway reconciliation report fails, the job's Status will say Error. Jobs can fail for a variety of reasons. The following is a list of common errors:

  • Zuora could not connect to the gateway to retrieve the source information. This can happen, if for example, the credentials were incorrect.
  • Zuora was able to connect, but could not find the source settlement report, perhaps because the automatically generated source file name was wrong for some reason.
  • Zuora connected and retrieved the file, but could not parse it. This can happen when the source file is created manually for testing, rather than by a well defined automatic process.

Once the first job attempt fails, Zuora will not retry retrieving the report. However, you have three options in which to retrieve the report:

Retry Option Description

Simply retries retrieving the report using the same default job information.

Retry Upload File

Retries retrieving the report by allowing an upload of a file from your local directory.

Retry File Name

Retries retrieving the report using the specified file/source name.

Real-Time Reconciliation 

Currently, this feature is only supported by the GoCardless and Stripe v2 gateway integrations. See Real-Time Reconciliation for more details.