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 Z-Payments. The response code and response message, Transaction ID number (a unique transaction identifier issued by the gateway), and often a Bank Identification Number will be displayed in Zuora on the payment detail page; this information is important to have handy troubleshooting gateway issues. 

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. 

See also The Payments Value Chain to understand all the parties involved in payment processing and their roles. 


For failed transactions passed through your gateway, Z-Payments will provide 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.

Use Gateway Resources to Troubleshoot Errors

See Setting Up Payment Gateways 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 (in Z-Payments this is the Reference ID) for the failed payment. This Transaction ID is an alphanumeric number; for example, CLEF4CGE8AB8."

For help with troubleshooting gateway errors, view our payment gateway documentation here: