Skip to main content

How do I find out why a payment or refund transaction failed?


How do I find out why a payment or refund transaction failed?

For every payment transaction (this includes payment method authorizations, payments, void payments, and refunds), Zuora sends the transaction request to the payment gateway and the gateway replies back with a response code (for example, 110) and response message (For example, Insufficient Funds) indicating if the transaction was approved or declined. Zuora will map the approval to a payment status of "Processed" and a decline to a payment status of "Error" in Zuora Payments.

You must review your payment transactions on a regular basis for any errors that occur and follow up with either the customer, payment gateway, processor, or even card issuing bank (depending on the type of error) to address the issue.  Most errors are the result of invalid payment methods, such as credit cards with insufficient funds or are expired. For invalid credit cards, we recommend following up with the customer immediately to request an alternative or updated payment method (you can automate this process using customer notifications).

On rare occasions, there may be errors with the gateway connection itself. In this case, contact the payment gateway. 


Use information on the payment detail page

For failed transactions passed through your gateway, Zuora presents some important information on the payment detail page such as the gateway Response Code, Response Message, Bank Identification Number, as well as a Reference ID. These errors can be translated based on each gateway's response code definition. 

In the Zuora UI, navigate to Payments > Payments and then click the payment number link in the list to open the payment detail page.

Export and use the payment transaction log

To find out more details than the information on the payment detail page, you can export the payment transaction log and use the request and response strings to analyze the transaction failure.

  1. In the Zuora UI, navigate to Reporting > Data Sources.
  2. In the Data Source field, select Payment Transaction Log.
  3. Add fields to be exported, such as Gateway, Gateway Response Code, Gateway Response Code Description, Request String, and Response String.
  4. Add filters, such as the payment number of the failed payment.
  5. Click export.


The payment transaction log will be available in the file list for downloading when it is ready. If the error is returned from the payment gateway, you can send the information in Request String and Response String to the payment gateway for further investigation.

See Payment Transaction Log data source for more information about this data source.

Use gateway resources to troubleshoot errors

See the Troubleshooting Gateway Errors section in the article for each supported payment gateway for more information on how to troubleshoot gateway errors.

For example, our PayPal gateway documentation states: 

There are several ways to obtain information on gateway errors:

  1. Refer to the PayPal developer's guide for the PayPal product you are using for information on specific gateway errors.  You should search under key words such as: Response to Transaction Requests, Transaction Response values, Result Code, Response Message, and Explanation. Links to the guides are available under the Test Credit Cards and Testing Scenarios section above.
  2. Look up the transaction by the transaction ID number (in the Zuora payment detail page, this is the Reference ID and Secondary Reference ID numbers) in your virtual terminal or merchant account to see if more information is provided. Zuora receives and displays to users the gateway RESULT Value (for example, 12) and RESPMSG Text (for example, Declined), but often additional details are available in your merchant account.RESPMSG Text (for example, Declined), but often additional details are available in your merchant account.
    • If you are using Payflow Pro's PayPal Manager, see Searching Transactions on PayPal's website for additional information.
  3. View PayPal's Website for Result Values for Transaction Declines or Errors and API Error Codes
  4. If you require additional information, you can contact the PayPal Help Center.
    • Search their knowledge base for the error you are encountering.
    • Log a PayPal MTS support ticket. When contacting the PayPal Help Center, to receive information about previous transactions in your account history, you must provide the Transaction ID (the Reference ID in Zuora Payments) for the failed payment. This Transaction ID is an alphanumeric number; for example, CLEF4CGE8AB8."