PayPal is one of the most popular payment gateways with many different products. Zuora supports PayPal Payflow Pro BYOB (Bring Your Own Bank) and Website Payments Pro Payflow Edition (also called Website Payments Pro), as well as PayPal Adaptive Payments. We also support these products (with exception of Adaptive Payments) if they are used with PayPal Express Checkout. Configuration of PayPal Adaptive payments will be covered in a separate article.
Configure the PayPal Payflow Pro or Website Payments Pro Gateway
To set up PayPal as your gateway, enter your PayPal credentials in the Z-Payments Settings > Setup Payment Gateway page.
When selecting a Gateway Type, choose PayPal Payflow Pro if you are using PayPal Payflow Pro BYOB, Website Payments Pro 2.0, or Website Payments Pro 3.0. Zuora integrates with these three products using the Payflow APIs, thus you can configure any of those products in Zuora using this gateway type.
Common Fields for Configuration
There are some common fields you must complete for every gateway configuration. We recommend reviewing our Setup Payment Gateway documentation for information on these common fields:
- Use Gateway Test Environment
- Cards Accepted
- Default Authorization Amount
PayPal payment processor does not accept $0.00 authorization amounts. If you are using Website Payments Pro (which uses PayPal processor, you can use any authorization amount above $0.00.
- Verify new payment method (optional)
- Verify updated payment method (optional)
In addition to the common fields, every gateway has unique requirements and information (such as credentials) that you must provide to configure the gateway in Zuora.
If you are using the PayPal Payflow Pro product, the credentials to configure the gateway in Zuora will be the same as your login credentials for PayPal Manager. If you are using the PayPal Website Payments Pro product, you should request Payflow Pro API credentials and configure those credentials in Zuora.
Paypal's terminology is slightly different from Zuora's terminology for the components of your login. The following table shows how a term is displayed in the Z-Payments Settings and what it corresponds to in Paypal. See Setting Up Payment Gateways for more information on setting up a payment gateway in Z-Payments.
|Zuora Term||PayPal Term||Comment|
|Partner||Partner||Typically Paypal is the partner, but may also be Verisign depending on how your account is set up by PayPal.|
|Merchant ID||Merchant Login or Vendor||You are the merchant|
|User ID||User||Typically, this is the same as the Merchant Login|
If you are using credit card reference transactions, you may select this option so that Zuora marks transactions submitted to PayPal as recurring. For recurring transactions, additional security checks (for previously authorized transactions) may be disabled in PayPal, allowing for reduced fees and greater acceptance with your merchant bank. For example, recurring transactions are not screened through fraud filters. Please check with your merchant account provider to verify that this is available and appropriate for your account.
Testing Your Configuration
Accessing Your Gateway's Test Environment
When configuring the PayPal payment gateway in Zuora, you can indicate whether you would like to use the PayPal test environment or the PayPal Production (Live) environment.
- If Use Gateway Test Environment is selected, Zuora will direct payment transactions to the following test environment which is a test simulator at
https://pilot-payflowpro.paypal.com(This URL is the API entry point for a test environment dedicated to PayFlow)
- If Use Gateway Test Environment is not selected (disabled), Zuora will direct payment transactions to the following production environment:
https://payflowpro.paypal.com(API entry point).Your credentials will be the same for both test and production environments, which both requires Payflow credentials. Zuora ensures your payment transactions are routed to the right environment based on whether the Use Gateway Test Environment is selected.
The UI entry point for
Test Credit Cards and Testing Scenarios
When testing transactions through the Zuora integration of Payflow Pro, Website Payments Pro Payflow Edition, and Website Payments Pro integrations, you should refer to the following developer's guides for more information:
- Payflow Pro Developer's Guide (see Chapter on "Credit Card Testing")
- Payflow Gateway Developer Guide (see Chapter on "Testing Transactions")
The integration uses the https://pilot-payflowpro.paypal.com simulator for testing, thus we refer you to the instructions in the Payflow guides. The developer's guides include information on generating payment errors based on the transaction amount used for testing. If you use a different credit card number for testing that is not listed in the developer's guide, it may also fail the transaction.
Test Credit Cards and Test Scenarios Will Depend on the Sandbox Used
If you are using the
https://pilot-payflowpro.paypal.com (Payflow Sandbox) for testing, you should follow the instructions in the Payflow Pro Developer's Guide. The Payflow Sandbox uses specific credit card numbers and generating transaction results and responses are handled differerently than with the PayPal Sandbox Sandbox.
By default, any merchant testing transactions via Zuora will be using the
https://pilot-payflowpro.paypal.com test simulator.
Most merchants will use use
https://pilot-payflowpro.paypal.com when testing in Zuora, unless PayPal has approved and linked your
https://www.sandbox.paypal.com account to
https://pilot-payflowpro.paypal.com (for example: if you have a Sandbox Pro account). Check with PayPal Merchant Technical Support or the Payflow Operations team to determine if you have a PayPal sandbox account linked to Payflow. If you have these accounts linked, follow the testing instructions in the PayPal Sandbox User Guide.
The PayPal Sandbox does not have a list of specific credit cards to use, however, these are your options:
- You can follow the instructions to add a credit card account to a test account.
- You can generate credit card numbers in sandbox.paypal.com.
- You can use a live card in your www.sandbox.com account for testing. This transaction will not go to a live environment it will only be sent to the Sandbox test environment.
Website Payments Pro uses PayPal as a payment processor and Payflow Pro BYOB uses a non-PayPal payment processor, therefore the testing environments and test credit card numbers are different between the two test environments. We recommend contacting your PayPal MTS support team for their recommended testing documentation.
For the Payflow Sandbox, to generate test transactions with specific decline errors, you would:
- Use a test credit card # provided in the Payflow Pro Developer's Guide (see Chapter on "Credit Card Testing"). The use of any other test credit card number will generate a decline.
- Create a payment transaction in Zuora with the appropriate payment amount to generate the result code you want to see. For example, the Payflow guide states that a payment transaction amount of $0-$1000 will generate Result = 0 (Approved). For transaction amounts of $1000-2000, certain amounts in this range will garner an error/declined Result.To generate a specific error, take the amount of $1000 and increase an amount matching the error code you want to produce (for example, transaction amount $1013 will generate an error of 13-Referral). A transaction amount greater than $2000 will generate a result of 12-Declined.
For the PayPal Sandbox, to generate test transactions with specific decline errors, you would:
- Generate a test credit card number per the instructions in the PayPal Sandbox User Guide.
- Create a payment transaction in Zuora using a payment amount matching the error code for the result you wish to generate (see PayPal API Error Codes for a list of errors).
Here are some sample payment amounts you can test:
1. Amt = 107.52
Error: 12 -- Declined: 10752-Please use a different payment card.
2. Amt = 150.50
Error: 12 -- Declined: 15005-This transaction cannot be processed.
3. Amt = 107.55
Error: 6 -- Invalid or unsupported currency code: 10755-This transaction cannot be processed due to an unsupported currency.
The errors you choose to test, have to:
Be valid errors for credit cards if you are testing a credit card payment method versus testing PayPal payment method.
Be a valid error for the transaction type you are testing, for example: PayPal API () DoAuthorization = Payment Method Authorization and PayPal API () DoCapture = Sale, Payment
General Testing Information
Zuora has been certified with PayPal as an integration partner and maintains the integration on an ongoing basis, thoroughly testing the integration with every new release. The PayPal integration documentation is helpful if you are integrating PayPal directly with your website (for example, to support the creation of Billing Agreement IDs), then you may need to refer to the integration guides. However, you do not need to perform any integration or certification testing to submit transactions to PayPal via the Zuora application. The intended audience for the integration guides are technical integrators, however, these documents can be helpful to non-technical integrators who can refer to it for information on testing and troubleshooting gateway errors (as described in the following section).
Performance and Volume Testing
In general, gateway testing environments are intended to give merchants the opportunity to test their gateway and integrations to their gateway, in order to work out any bugs before going to the production environment. Some gateway test environments are shared amongst multiple merchants, and other gateways provide unique testing environments for each merchant. Additionally, gateway test environments (also referred to as certification or sandbox environments) do not have the same high availability or performance capability as production environments. As such, they are not intended for load testing. Merchants performing high volumes of load testing that puts a stress on a shared test environment may receive a warning from the gateway or have their access to the testing environment suspended.
Troubleshooting 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:
- 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.
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
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.
- 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.
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.
Additional Gateway Information
Clarification on the PayPal Products Zuora Supports
Zuora supports PayPal Payflow Pro, Website Payments Pro Payflow Edition, and Website Payments Pro. Here is some additional information that may help you in understanding how these products vary:
- When Zuora refers to Website Payments Pro 2.0 and Website Payments Pro 3.0, the 2.0 and 3.0 versioning are internal references used by Zuora and PayPal, however, these products are generally referred to as Website Payments Pro Payflow Edition and Website Payments Pro, respectively.
- PayPal Payflow Pro is a robust gateway product in which the merchant can choose their own internet merchant account (bank) and processor to use with the gateway rather than using PayPal as the internet merchant account or payment processor.
- Website Payments Pro 3.0 combines gateway services with an internet merchant account, making it easy for merchants to sign up for a single solution with relatively lower costs than Payflow Pro. With this account, PayPal is the payment processor. (It's often more cost effective using a single provider for payment gateway, merchant bank, and payment processing services).
- PayPal acquired the Payflow gateway from Verisign back in 2005. This gateway has more features and functionality than the gateway which comes with Website Payments Pro 3.0.
- Express Checkout for PayPal is similar to Google Checkout in that you can add a button on your checkout page that allows customers to pay using PayPal. Express checkout is inherently available with Website Payments Pro, and it is also available with Payflow Pro as long as the merchant enables PayPal payment method.