Skip to main content

Electronic Payment Processing

Zuora

Electronic Payment Processing

Zuora supports various electronic payment methods. Zuora can process electronic transactions in either of the following ways:

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:

sync-payment-flow.png

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

Overview

In the synchronous payment flow, the status of electronic direct debits (labeled as ACH and Bank Transfer in Zuora) might not be accurate because the Processed status is set based on the initial approval or decline from the payment gateway. It does not mean the payment is truly completed and settled.

Zuora offers opt-in support for the asynchronous payment flow for electronic ACH and Bank Transfer transactions. The Pending payment status is included to indicate that transactions are awaiting settlement confirmation, in addition to the other statuses available in the synchronous payment flow (Processing, Processed, Error, Voided). If this support is enabled, after you create an electronic ACH or Bank Transfer payment through the UI or the REST API operations, the payment is in a Pending status upon successful network communication with the gateway. For descriptions of Payment Status values, see Payment Status values.

The Asynchronous Payment Statuses feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters.

The following chart displays the asynchronous payment flow:

async-payment-flow.png

Payments in the Pending status can be canceled, applied, and unapplied, but cannot be refunded or transferred. To transition from a Pending status to another status, you must either cancel the payment or use any of the following Gateway Reconciliation services:

If the payment is settled, the Payment Status field is set to Processed and the Gateway State field is set to Settled. If the payment is rejected, the Payment Status field is set to Error and the Gateway State field is set to FailedToSettle. Since the gateway is moved to Error, no external refund is created. If the payment is reversed before it is settled, the Payment Status field is set to Processed and the Gateway State field is set to Settled. An external refund is created to reverse the journal entry. 

Enable the Asynchronous Payment Statuses feature

Prerequisites

  • To use the Asynchronous Payment Statuses feature, the Invoice Settlement feature must be enabled.
  • Make sure your payment gateway integration supports this feature. The following payment gateway integrations do not support this feature:
    • Authorize.net
    • Chase Paymentech Orbital, API v6.3.0
    • CyberSource Enterprise Gateway, API v1.28
    • CyberSource Enterprise Gateway, API v1.97
    • Cybersource Tokenization
    • Worldline Global Collect Legacy (previous Ingenico ePayments GlobalCollect)
    • IP Payments
    • Merchant eSolutions
    • Moneris (eSelectPLUS Canada)
    • PayPal Adaptive Payments Gateway
    • Paypal Payflow Pro
    • QValent Quick Gateway
    • Vantiv
    • Verifi Global Payment
    • WorldPay (Corporate Gateway)
  • Make sure you have already enabled a form of Gateway Reconciliation. Otherwise, transactions will be left in the Pending status.

Enable the feature

Complete the following steps to enable the Asynchronous Payment Statuses feature:

  1. Click your username in the upper right and navigate to Settings > Payments > Define Payment Rules.
  2. Click Edit.
  3. Select Yes for Enable 'Pending' statuses for delayed payment confirmations and then click Save.

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 the payment is stuck in processing, please contact Zuora 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.

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.

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

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

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
BACS 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
iDEAL Yes for recurring payments via SEPA 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
Google Pay Yes Yes Yes

PayPal Express Checkout

PayPal Yes Yes 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
Citi ACH Yes Yes Yes

Troubleshoot transactions stuck in Processing status

See Update the status of payment stuck in Processing for more information.