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.
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.
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:
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.
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.
https://pilot-payflowpro.paypal.com(This URL is the API entry point for a test environment dedicated to PayFlow)
https://payflowpro.paypal.com(API entry point).
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:
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.
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:
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:
For the PayPal Sandbox, to generate test transactions with specific decline errors, you would:
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
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).
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.
There are several ways to obtain information on gateway errors:
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 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:
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.
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.
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.
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.
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:
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:
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.
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.
For Payments Attempted Through the Z-Payments Interface
To check for error payments:
Payment CSVfrom the Export Data list.
Payment Datefrom the Extract By list, and
Todayin the Duration list.
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.
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.
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: