Electronic payment processing

Synchronous payment flow

In Zuora, by default, the payment status is synchronously set based on the response that Zuora receives from the network. The Payment Status field can be one of the following values:

• Processing
• Processed
• Error
• Voided

The following chart displays the synchronous payment flow:

For payment card (credit card or debit card) transactions, the response from the card network is usually an immediate approval or a decline. 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.

For ACH and Bank Transfer (also known as Direct Debit) transactions, there is no immediate approval for a payment. Instead, the payment gateway will respond with an initial approval or decline after checking the format of the bank account number, the transit routing number, and other specific Bank Transfer information. If Zuora gets an initial approval from the payment gateway, the Payment Status is Processed. If a decline is received by Zuora, the Payment Status is Error. A processed payment in Zuora will decrease the invoice balance, even though the ACH or Bank Transfer payment might fail later. The Processed status for ACH or Bank Transfer transactions does not mean the payment is truly completed and settled. You must use gateway reconciliation and leverage other status fields such as Gateway State to determine the true status of the payment.

For descriptions of Payment Status values, see Payment Status values.

Asynchronous payment flow

Payment Status values

The following table provides descriptions of Payment Status values.

Value	Payment Flow Type	Description
Processing	Synchronous and Asynchronous	The payment is being processed or the payment is on hold because appropriate confirmation is not received from the gateway. 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 Zuora receives a 500 error from the gateway during payment processing, the payment status is set to Processing rather than Error to prevent duplicate charges. A 500 gateway error does not always indicate the payment failed on the gateway side. It can still be successful despite the 500 error. Setting the status to Error might cause payment retries, leading to double charges. If the payment is stuck in processing, you can either update the status manually or contact Zuora Global Support.
Processed	Synchronous and Asynchronous	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 Bank Transfer: In a synchronous payment flow, it indicates that an initial approval to request payment is received from the payment gateway. In an asynchronous payment flow, it indicates that the payment is settled or reversed.
Error	Synchronous and Asynchronous	The payment is declined by the network due to some errors. 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 Bank Transfer, this status indicates that the settlement has failed for some reason.
Voided	Synchronous and Asynchronous	The payment is voided before it is settled.
Pending	Asynchronous	The payment is awaiting settlement confirmation.

Gateway Reconciliation state consideration

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, Gateway State can be one of the following values:

• Submitted
• NotSubmitted
• Settled
• FailedToSettle

After the payment transaction is submitted to the bank successfully, Gateway State is Submitted. Otherwise, Gateway State is NotSubmitted. If 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 Bank Transfer, it is possible that settlement fails then Gateway State is changed from Submitted to FailedToSettle.

Gateway State is displayed in the Additional Fields section of the Payment Details page in the Zuora UI. You can also 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. The update will be recorded in Audit Trail.

• Update it through any of the following API operations:
  • Update a payment. You must have the Edit Payment Gateway Status user permission to perform this action.
  • Payment Gateway Reconciliation
• Update it through the UI. Edit the Gateway State field in the Additional Fields section of the Payment Detail page. You must have the Edit Payment Gateway Status user permission to perform this action. See Review and edit payments for more information.

The following table provides descriptions of Gateway State values.

Value	Description
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.

Troubleshoot transactions

• If you find a payment stuck in Processing status and you want to manually update the transaction status, see Update the status of payment stuck in Processing.
• If you encounter declined payments with a timeout error, it may be because Zuora does not receive valid responses after multiple retry attempts, possibly caused by network disruption.
  • For payments initiated through the UI or API operation, you will need to manually retry the payment.
  • For payments triggered by Payment Run, the invoice balance will be addressed in the next Payment Run cycle.
• To find out more information about the communication between Zuora and the gateway for payment method creation, verification, and payment processing, see Discover information about payment method creation and payment processing.