Troubleshoot PayPal Payflow Pro or Website Payments Pro Payflow Edition gateway errors
Obtain information on payment gateway errors
There are several ways to obtain information on gateway errors:
- View the transaction in your PayPal Manager (for Payflow Pro merchants) or PayPal.com (for Website Payments Pro merchants) to see if there is more information provided with the transaction details in PayPal. 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.
- If you are using Payflow Pro's PayPal Manager, see Searching Transactions on PayPal's website for help in looking up transactions.
- Search for the error in PayPal's MTS (Merchant Technical Support) Center, go to the Answers tab and type in the error.
- Check the PayPal maintenance updates.
If PayPal had any downtime due to maintenance updates, this can result in this type of error from not being able to access the PayPal systems.For PayPal maintenance updates, check here: https://www.x.com/node/304976. - 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. Here are the links to these guides:
-
Payflow Pro
- Website Payments Pro Payflow Edition
- Website Payments Pro
-
- View PayPal's Website for Result Values for Transaction Declines or Errors and API Error Codes.
- 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."
Make Sure You Are Not Re-Trying an Invalid Card Too Many Times
We recommend that you check the payment in Zuora to see how many times the same payment method has been retried for payment and failed. If there have been several retries, check the error messages from the beginning with the first failure and the more recent failures to determine if the error message is the same. If a merchant tries to process a payment against the same credit card too many times despite receiving errors, this could trigger warnings to the card issuing bank. The card issuing bank may place an alert on the account and not allow any further transactions from the merchant using that payment method. When a mechant has been flagged, the error received on the payment may be not state the reason why, instead it might be a generic error such as 12--Declined or 1000-Generic Processor Error: 1000-Internal Error. In this case, the merchant (Zuora customer) should work with their merchant acquirer/processor to see if they can identify the problem with the payment method. If the processor does not know, then the merchant and/or the card holder can try calling their card issuing bank to look into the issue.
General 12: Declined Errors
General credit card decline errors from PayPal may have a Response Reason Code "12" and Response Reason Text "Declined." Search for this error in PayPal's MTS (Merchant Technical Support) Center and you will find that this error may occur for a number of reasons including:
- Invalid amount (only payments 99999.99 and below can be processed as a single payment transaction). For certain types of credit cards (American Express, Discover), the transaction amount must be greater than $1.
- Amount exceeds available funds, may need a voice authorization from the bank to proceed.
- The transaction was declined by the card issuing bank. PayPal only returns the response, and the actual approval or decline comes from the bank.
- If its a newly activated credit card account, the card networks have not been updated yet. You can retry the payment at a later time.
- Issues with the expiration date (invalid format, expired, or not matching).
- Card security code (also known as CVN, CVV, CVV2, the 3 or 4 digit security code on the back of a credit card) does not match.
- A real credit card is being used for transaction sent to the test server.
If you have followed the troubleshooting steps above and cannot determine the root cause of the error, you may need to have the card holder contact their bank for more information. Meanwhile, you can request an alternative form of payment from the end customer.
Response Code 12: Declined: 15005-This transaction cannot be processed.
You may receive an error response code 12 -- Declined that contains a response message which may or may not clarify the reason for the decline. We always recommend you check the credit card number, expiration date, and transaction information to make sure they were entered correctly. If this does not resolve the problem, have the customer call their card issuing bank to resolve.
PayPal support has said that the 15005 response code means that the transaction was declined by the cardholder's issuing bank. The card holder will have to call his or her card issuer for further information, as banking privacy regulations prevent the issuer from sharing the decline reason with PayPal. The recommended handling path for this error is to inform the card holder (end customer) that the transaction has been declined, and that he or she should contact his or her credit card issuer for details on the reason the transaction was declined. Additionally, request from the end customer an alternative form of payment.
Frequency of General Declines
General declines are fairly common, but a high rate of decline with this error is worth investigating further with your payment gateway and processor to rule out any issues with your merchant account. If you notice the declines happening with a specific card issuing bank, you may want to contact that bank to find out more information.
Limited Free Trials and Credit Card Declines
If your company offers a limited free trial where you obtain and authorize credit cards in advance, but charge for payment on a future date (such as tomorrow, a week, or a month later) there's a risk that the credit card may no longer be valid when the future payment is collected (in gateway terminology, this is sometimes referred to as capturing a payment). The status/validity of a credit card can change easily and frequently. A customer's credit card can have sufficient funds today, but the customer makes a large purchase tomorrow that results in their account being low in funds. If you happen to charge their card when their account has insufficient funds, you will get a credit card decline. The same customer can pay off their credit card debt tomorrow, and their card will once again be valid with sufficient funds. For this reason, we recommend configuring your payment retry rules to retry credit cards (for example, you can retry a card once every 24 hours, up to a maximum of 3 attempts).There are many benefits to offering limited free trials, but its important to understand how a credit card can be valid one day and be declined the next. Again, if you feel these types of declines are occurring at a high rate, please contact your payment gateway and processor immediately to investigate the issue.
26: Invalid Vendor Account (Error with Credentials)
If you are receiving a Response Code: 26 and Response Reason Text: Invalid vendor account, then the payment gateway user-id/password information is incorrect. Make sure you are using your Payflow credentials when configuring your payment gateway in Zuora (see above section on Credentials for more information).
<h4">1000: Generic processor error: 10001-Internal Error
On some occasions, this error could be due to a problem with the funding source used; this funding source could be a credit card or a bank account linked to a PayPal account if PayPal is the payment method. If you have retried the payment more than once and received the same error message, the recommended handling path for this error is to inform the card holder (end customer) that the transaction has been declined, and that he or she should contact his or her credit card issuer for details on the reason the transaction was declined. Additionally, request from the end customer an alternative form of payment.
Other possible reasons for 10001 Errors:
- There was a PayPal Maintenance downtime when the payment transaction was submitted. Check here to see for maintenance notices: https://www.x.com/node/304976. The contact person listed on your merchant account should also be receiving notifications from PayPal of any planned maintenance.
- The card failed the CVV check at least six times within a 30 day period.
- The billing country does not match the billing country on record for the card holder.
- The state name was not passed using the correct state abbreviation.
TimeOut Errors
When a payment is attempted using the PayPal payment gateway, if the processor takes longer than 120 seconds to process such payment transaction, PayPal can return timeout errors for the payment.
PayPal can generate the following timeout errors:
- 104: Timeout waiting for processor response. Try your transaction again.
- 1000: Generic processor error: 10001 - Timeout processing request
If a payment results in a timeout error, it is unclear whether or not the payment processor eventually processed the payment successfully or if the payment failed.
Most payments do not take longer than 120 seconds to process, but some do. For these outliers, Zuora recommends manual intervention by checking in the PayPal virtual terminal to verify whether or not the payment was successful. It is important to check on the final payment status before you attempt another payment on the same charge to avoid overcharging the end customer.
Addressing PayPal Timeout Errors
The following describes how to address PayPal time out errors, based on whether the payment was attempted through a subscribe()
call or through the Z-Payments interface.
For Payments Attempted Through a subscribe Call
In a subscribe()
call, Zuora will attempt to process a payment for the subscription. If a payment was processed successfully, the customer account/subscription/invoice/and payment information will all be stored in Z-Billing.
In the event the subscribe call fails due to a payment error, the application rolls the data back and will not create a customer account, subscription, invoice, or payment in Z-Billing. In such cases, we suggest you monitor timeout errors in the API by setting up an alert that is sent to you when there is a payment timeout error. When you receive this alert, you can decide on a process for handling such errors.
For example:
- In the event this error occurred when an end user attempts to sign up for your service, you can do the following:
- Decide whether or not to allow the end user to continue the sign up process, or display an error stating there is a problem with their order.
- Ask the end user to please try again later or let the end user know that your company has been notified of this error.
- Ask the end user to enter a different payment method
- You should always go to the PayPal virtual terminal to verify if the payments with error code 104 or 1000 timeouts were successfully processed by the payment processor.
For Payments Attempted Through the Z-Payments Interface
To check for error payments, you can export data from the Payment data source. To export data from the Payment data source:
-
Navigate to Reporting > Data Sources.
-
From the Data Source field, select Payment.
The Fields panel displays the fields provided by the Payment data source.
-
In the Payment folder, select Gateway Response Code and Gateway Response Message.
The exported data will contain columns called "Payment: Gateway Response Code" and "Payment: Gateway Response Message" that list the gateway response for each payment. To export more information about each payment, select more fields in the Fields panel. Alternatively, select Select All "Payment" Fields.
-
In the Time Frame panel, select Payment > Effective Date from the Filter By field, then select Daily > Today from the Date Range field.
-
Click export.
When the export is complete, the exported data is available for download at the bottom of the page.
-
After exporting the data, check the "Payment: Gateway Response Code" and "Payment: Gateway Response Message" columns for errors. For example, Generic processor error: 10001-Timeout processing request.
-
Go to the PayPal virtual terminal to verify if the payments with error code 104 or 1000 timeouts were successfully processed by the payment processor.
If they were successfully processed, add an external payment in Zuora to show that the invoice was paid. If it was not successfully process, you can re-attempt the payment using a payment run or create a payment.
Checking for Payments with Timeout Errors
It is important to handle payments with error code 104 or 1000 timeouts as soon as you are made aware of them (we recommend checking daily for timeout errors), especially if your company has set up daily payment runs to occur. If payment was attempted for an open invoice and such payment resulted in an error, the next time a payment run is executed it will attempt to collect payment on the same invoice. Therefore, ensuring the payment was not already collected in PayPal ensures your end customer will not be overcharged.
Avoiding Repeated Charges
If a payment that timed out was successfully processed in PayPal, you can reflect this in Z-Payments to ensure that your customer is not charged again for the same invoice by going to Z-Payments and creating an external payment for the invoice that has been paid.