Skip to main content

Set up and configure a PayPal Payflow Pro or Website Payments Pro Payflow Edition gateway instance

Zuora

Set up and configure a PayPal Payflow Pro or Website Payments Pro Payflow Edition gateway instance

Set up and configure a PayPal Payflow Pro or Website Payments Pro Payflow Edition gateway instance by using the information in this article, including configuration procedure, descriptions of the configuration fields, and reference for testing the payment gateway.

Prerequisites

Enable the payment gateway integration for your tenant. See Enable payment gateway integrations for your tenant for instructions.

Procedure 

Perform the following steps to set up and configure a PayPal Payflow Pro or Website Payments Pro Payflow Edition gateway instance in Zuora:

  1. Click your username in the upper right and navigate to Settings > Payments > Setup Payment Gateway
  2. On the Configure Gateway Instance tab, select PayPal Payflow Pro from the Gateway Type drop-down list. Zuora integrates with the following products using the Payflow APIs, thus you can configure gateway integrations for any of the following products in Zuora by using this gateway type:
    • PayPal Payflow Pro BYOB
    • Website Payments Pro 2.0
    • Website Payments Pro 3.0
  3. Click Create Gateway.
  4. On the gateway settings page, specify values for the configuration fields. See below for more information on the fields.
  5. Click Save Gateway Information.

Configuration fields 

Common configuration fields

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: 

  • Name
  • 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)

Credentials

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 Zuora Payments Settings and what it corresponds to in Paypal.

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
Password Password   

Rules

Support recurring

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.

Test the 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 https://pilot-payflowpro.paypal.com and https://payflowpro.paypal.com is at https://manager.paypal.com.

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: 

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 ssed

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.

If you are using the https://www.sandbox.paypal.com (PayPal Sandbox) account for testing through Zuora, you should following the steps in the Sandbox User Guide for adding a credit card account. 

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.

Negative testing 

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

Viewing test transactions in UI

Test transactions sent to the Payflow Sandbox can be viewed in the UI by logging into manager.paypal.com. If your PayPal sandbox account linked to Payflow, then you can view your transactions in https://www.sandbox.paypal.com.

General testing information

Integration testing

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.