Merchants with PayPal Business Accounts and API Access to Adaptive Payments can simply enter their credentials in Zuora to seamlessly integrate with Adaptive Payments. Standard payments (PayPal’s "Simple" Adaptive Payments) are supported by passing in the preauthorization into Z-Payments so that Z-Payments can manage the payment collections.
PayPal is one of the most popular payment gateways with many different products. Zuora supports PayPal Adaptive Payments, PayPal Payflow Pro BYOB (Bring Your Own Bank), Website Payments Pro Payflow Edition, and Website Payments Pro.
This article focuses on the configuration and use of the Zuora/PayPal Adaptive payments integration. Like our other pre-integrated gateways and processors, Adaptive Payments supports both one time and recurring payment transactions. There are three different types of approvals available for Adaptive Payments (Explicit Approval Payments, Implicit Approval Payments, and Preapproved Payments).
Zuora's Adaptive Payments Integration supports Preapproved Payments. With a Preapproved payments, during your order flow (specifically when capturing and storing the payment method), you would redirect your customer from your site to paypal.com to set up preapprovals that allow you to collect future payments using their designated payment method. PayPal will return a preapproval key which you will store in Zuora and used for recurring payments. Although your customer may use a credit card as the designated payment method when setting up preapprovals in PayPal, only the preapproval key (not the secure credit card information) is stored in Zuora. The payment method in Zuora is called the "PayPal Payment Method" (similar to how the Billing Agreement ID works in Zuora).
- You (the merchant) must have a PayPal Business account set up.
- Certain Adaptive Payments features (such as Pre-Approved Payments) are considered advanced services by PayPal; these services must be enabled by PayPal in your merchant account before you can use them.
Any third-party calling the PayPal Adaptive Payments API on your behalf also requires PayPal approval to use advanced services. Zuora has obtained permission from PayPal to use these services on behalf of our merchants who are signed up for PayPal Adaptive Payments.
- The customer sending the payment to you and the receivers of the payment must also have a PayPal account of any type. The receivers of the payment must have a PayPal account in order for the funds to be deposited into their account.
- Review the PayPal Adaptive Payments Developer Guide for an understanding of how Adaptive Payments works and how to integrate pre-approved payments with your e-Commerce website.
Configure the PayPal Adaptive Payments in Zuora
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(Adaptive Payments).
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
Your PayPal account's identification. This ID is issued by PayPal.
This is your API User Name.
This is your API Password for your API User Name (above).
This is your signature.
This is the email address for the receiver of the payments. Since Zuora only supports Simple Payments where the merchant is the receiver, your (the merchant's) email address for your PayPal account can be used here; this should be the PayPal account in which you will receive the funds for payment transactions processed.
Similar to the Verify credit card rules for other payment gateway configurations, if the Verify new Pre-Approval Key and/or the Verify updated Pre-Approval Key are selected, Zuora will send a verification request (using the PayPal Adaptive Payments
Validate()) to check whether or not the Pre-Approval Key is still valid whenever a new payment method is created and/or when the payment method is updated.
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://svcs.sandbox.paypal.com/AdaptivePayments/ (API entry point).
- If Use Gateway Test Environment is not selected (disabled), Zuora will direct payment transactions to the following production environment: https://svcs.paypal.com/AdaptivePayments (API entry point).
Your credentials will be the same for both test and production environments.
Merchants can test their workflow using the PayPal Sandbox; go to developer.paypal.com to set up your test environment. The Sandbox App Id that is used is APP-80W284485P519543T. We recommend contacting your PayPal MTS support team for their recommended testing documentation.
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 Preapproval Agreements), 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 below).
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:
- 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. See the PayPal Adaptive Payments Developer Guide (search for "Pay Errors").
- 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.
- 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.
Additional Gateway Information
Support for Simple Payments
Adaptive Payments can be used to support the traditional payment where there is one sender of the payment (your customer) and one receiver of the payment (you, the merchant). For example, a customer purchases a subscription to your service and they make a single payment to you for the service.
The Adaptive Payments API is flexible and enables the ability to pay, one to one (simple payments) or one to many (parallel payments), and pay a primary receiver to multiple secondary receivers of the payment (chained payments). Zuora's integration currently supports the PayPal Adaptive simple payments only.
Approvals for Payments
PayPal requires the sender (your customer) to approve all payments being made. The sender can provide approval via 3 different methods:
- Method 1: Preapproved Payments (Recommended for Recurring Payments)
Your customer logs into PayPal only once to set up a preapproval agreement that lets you (the merchant) charge their PayPal account for recurring payments. Zuora supports preapproved payments.
- Method 2: Explicit Approval Payments
The sender logs into PayPal.com to approve every single payment. This requires contacting the customer on a recurring basis (as frequently as their subscription is billed) to approve payments before payment can be collected.
- Method 3: Implicit Approval Payments (Not Applicable for Merchants Using Zuora)
You (the merchant) are the sender of the payments and also the submitter of the payments to PayPal via the Adaptive Payments API. This is not applicable as your customer is the sender of payments and you are using Zuora to submit the transactions to PayPal.
Sample Preapproved Payments Flow
Here is a sample workflow for how a PayPal payment method gets created and stored in Zuora after obtaining the preapproval key:
- Customer signs up on your (the merchant’s) website and subscribes to your services.
- Customer completes their purchase by selecting a payment method that they wish to use. They select PayPal. (This is the only payment method supported for PayPal Adaptive Payments.)
- You initiate a
preapprovalrequest with PayPal. PayPal returns a preapproval key that is used when you redirect the end customer's browser to PayPal's site to complete the pre-approval agreement. The pre-approval agreement allows you to charge their PayPal account for recurring payments.
On the pre-approval form, the customer will indicate:
- The duration of time in which they approve payments to be charged to their PayPal account (specifying a start and end date).
- The payment amount that can be deducted.
- The number of times payment can be deducted.
- You will call the Zuora API to create a PayPal payment method using the preapproval key from PayPal, then store the payment method in the customer account.
- The PayPal payment method can be used to process payments for the current order and future orders. You can submit a payment through Zuora to charge the customer’s PayPal account for the initial payment on that customer's subscription.
- Next month (or on the next billing day), you can charge the customer for their next recurring subscription fee using the stored payment method and pre-approval key in their Zuora customer account, without the customer having to log into PayPal again.
Review the PayPal Adaptive Payments Developer Guide (see Preapproved Payments Flow on page 23) to learn more about pre-approved payments and how to set up the workflow for pre-approved payment with your e-Commerce website.
Payment Method Supported
The Adaptive Payments integration only supports the PayPal Payment Method.
Void Payment is Not Supported
In general, payments can only be voided before the payment is settled. PayPal does not support the void operation with Adaptive Payments because it is dealing with only completed payments. The simple payments created using this integration settle immediately and thus this operation is not required for the integration. If you need to reverse a payment, you can create a Refund. Zuora supports referenced refunds for Adaptive Payments.