Gateway Reconciliation state consideration
Learn about the Gateway State in Zuora, its role in gateway reconciliation, and how it affects payment processing and status updates.
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. You must have the Edit Payment Gateway Status user permission to perform this action. For more detailed information, see Payments roles The update will be recorded in Audit Trail . For more detailed information, see Audit Trail overview
-
Update it through any of the following API operations:
-
Update it through the UI. Edit the Gateway State field in the Additional Fields section of the Payment Detail page. See Review and edit payments for more information.
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 use Payment Status .
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. |