Electronic Payment Processing

Payment Card Processing

For payment card (credit card or debit card) transactions, Payment Status is set based on the response that Zuora receives from the payment card network. The response is usually an immediate approval or a decline for a payment. For example, a Processed payment means that the transaction is approved for payment by the payment card network after the network checks the account information and available balance. If a decline is received from the payment card network, the Payment Status should be Error in Zuora.

ACH and Direct Debit Processing

For ACH or Direct Debit transactions, there is no immediate approval for a payment. Instead, the direct debit network will respond with an initial approval or decline after checking the format of the bank account number, the transit routing number, and other specific direct debit information. If Zuora gets an initial approval from the direct debit network, the Payment Status is Processed. If a decline is received by Zuora, the Payment Status should be Error. A processed payment in Zuora will decrease the invoice balance, even though the ACH or Direct Debit payment might fail later.

Gateway Reconciliation Consideration

The Gateway State in Zuora is mainly used for gateway reconciliation. Gateway reconciliation is a process that is performed by Zuora to verify that the electronic payment and refund transactions that are processed in Zuora match the transactions that are reported by the gateway.

The gateway reconciliation feature utilizes the gateway's reconciliation report (also known as settlement report) to automatically update Gateway State in Zuora. It can also automatically create an external refund when a rejected or reversed payment occurs. For more information about the gateway reconciliation feature and the supported gateways, see Gateway Reconciliation.

With Gateway Reconciliation enabled, the Gateway State can be one of the following values:

Submitted
NotSubmitted
Settled
FailedToSettle

After the payment transaction is submitted to the bank successfully, the Gateway State is Submitted. Otherwise, the Gateway State is NotSubmitted. If the Gateway State is changed to Settled in Zuora, it means the payment has been accepted and processed by the bank. For payment cards, payment settlement can take up to 3 business days. For ACH or Direct Debit, it is possible that settlement fails then the Gateway State is changed from Submitted to FailedToSettle.

Gateway State is displayed in the Additional Fields section of the Payment Detail page in the Zuora UI. You can use the Retrieve a payment API operation or Payment data source to retrieve the value of the Gateway State field.

To update the Gateway State field, use one of the following methods:

Edit the Gateway State field in the Additional Fields section of the payment details page. You must have the Edit Payment Gateway Status user permission to perform this action. See Review and edit payments for more information.
Use the Payment Gateway Reconciliation API operations.

If Gateway Reconciliation is not enabled, the Gateway State value always remains the same. For a processed payment, the Gateway State is Submitted. For a voided payment, the Gateway State is NotSubmitted. In this case, you can ignore Gateway State and focus on Payment Status.

Payment Status and Gateway State

For detailed descriptions about Payment Status and Gateway State, refer to the table below.

Field Name	Field Value	Description
Payment Status	Processing	The payment is being processed or the payment is on hold because appropriate confirmation is not received from the gateway. After Zuora receives the response from the gateway, the Processing payment status is updated to Processed or Error. If the payment status cannot be updated due to a certain reason when Zuora receives the gateway response, the Processing payment status is automatically updated to Processed or Error by Zuora later when any user of the tenant views this payment, regardless of whether the user has the update permission. If concurrent payment runs are configured on your tenant or concurrent payment run threads of Performance Booster are enabled, a payment might be in the Processing status for a while. To check and refresh the payment status in payment runs, see The payment is stuck in Processing status troubleshooting guide. If the payment is stuck in processing, please contact Zuora Support.
	Processed	The payment is approved by the network. For payment cards, an immediate approval is received for payment from the payment card network after the network checks the account information and available balance. For ACH or Direct Debit, an initial approval is received from the direct debit network after the network checks the bank account number, transit routing number, and other direct debit information.
	Error	The payment is declined by the network due to some error. For payment cards, a decline is received from the payment card network. It might be caused by insufficient balance or wrong account information. For ACH or Direct Debit, a decline is received from the direct debit network. It might be caused by the wrong direct debit information.
	Voided	The payment is voided before it is settled.
Gateway State	Submitted	The payment is submitted to the bank.
	NotSubmitted	The payment is not submitted to the bank.
	Settled	The payment is successfully debited from the payer and credited to the payee.
	FailedToSettle	A settlement error or a post-settlement exception occurs. The payment might be rejected by the bank, or a chargeback for credit card or a reversal for direct debit might occur.

Automatically resolving stuck payments and refunds

When processing payments or refunds, if appropriate confirmation is not received from the gateway, Zuora keeps the transaction in Processing status to prevent duplicate transactions from being attempted on the same billing documents. For transactions processed through the following payment gateway integrations, Zuora supports idempotent retry or inquiry call to automatically resolve payments or refunds stuck in the Processing status in Zuora and increase the success rate.

Idempotent retry

Gateway integrations in the following table support idempotency for safely retrying a transaction request. Hourly retry is performed on payments or refunds in the processing status. Once a retry is processed successfully, the transaction request is performed and the latest transaction status is returned from the gateway. Zuora updates the transaction status accordingly.

The following table shows the payment method types that support the idempotent retry for each gateway integration.

Gateway integration	Payment method type	Supported in payments	Supported in referenced refunds	Supported in non-referenced refunds
Adyen Integration v2.0	ACH	Yes	Yes	Yes
	Apple Pay	Yes	Yes	No
	Credit Card	Yes Also supported in Delayed Capture	Yes	Yes
	Credit Card Reference	Yes Also supported in Delayed Capture	Yes	Yes
	Google Pay	Yes Also supported in Delayed Capture	Yes	No
	SEPA	Yes	Yes	Yes
BlueSnap	ACH	Yes	No	No
	Credit Card	Yes	No	No
	SEPA	Yes	No	No
Chase Paymentech Orbital	ACH	Yes	Yes	Yes
	Apple Pay	Yes Also supported in Delayed Capture	Yes	Yes
	Direct Debit UK	Yes	Yes	Yes
	Credit Card	Yes Also supported in Delayed Capture	Yes	Yes
	Credit Card Reference	Yes	Yes	Yes
	Google Pay	Yes	Yes	Yes
	SEPA	Yes	Yes	Yes
Helix	Credit Card	Yes	Yes	Yes
Stripe v2	ACH	Yes	Yes	No
	Direct Debit UK	Yes	Yes	No
	Credit Card	Yes Also supported in Delayed Capture	Yes	Yes
	Credit Card Reference	Yes	Yes	No
	PAD	Yes	Yes	No
	SEPA	Yes	Yes	No
PayPal Express Checkout (support is only available in sandbox environments for now)	PayPal	Yes	No	No
WePay	ACH	Yes	Yes	No

Inquiry call

The Citi gateway integration supports inquiry calls on ACH transactions. After the transaction request is sent to the gateway, Zuora sends inquiry requests to the gateway and queries for the status of the transaction. Once the transaction status can be determined and retrieved, the latest transaction status is returned from the gateway and Zuora updates the transaction status accordingly.

Gateway integration	Payment method type	Supported in payments	Supported in referenced refunds	Supported in non-referenced refunds
Cit	ACH	Yes	Yes	Yes

Troubleshoot transactions stuck in Processing status

If you have a payment stuck in Processing status, take the following steps below to resolve the issue:

From the Zuora UI, search for the payment in processing status by navigating to Payments > Search Payments and enter the payment number.
From your search results, click the payment number link to access the payment detail information. When a user accesses the payment detail page, Zuora will attempt to retrieve the payment status. If the payment status is available, the payment status in Zuora will be updated to either Error or Processed. If the payment status is still indeterminate or unavailable, the payment will remain in Processing status and you can proceed to step 3.
In your customer account of the payment gateway provider, search for the payment, check the following questions, and provide the answers to Zuora Global Support so that we can update the payment status in Zuora:
- Does the payment exist in your payment gateway account?
- If the answer is "Yes" to the first question, provide the following additional information:
  - Was the payment processed successfully or did it fail?
  - What are the payment transaction reference ID and transaction result?
- If the answer is "No" to the first question, Zuora will set this payment to Error as the payment request failed to reach the payment gateway.