Zuora supports electronic payment processing using a variety of different payment methods such as credit cards, PayPal, debit cards, and direct debit (including ACH). Merchants planning to support the PayPal Billing Agreement ID (BAID) payment method via PayPal's Express Checkout must utilize the PayPal's APIs to create the PayPal BAID, which gets passed to Zuora to create the PayPal payment method. Such payment method can be used for processing payments in Zuora and payments can be one time or recurring.
This article provides you information on PayPal BAIDs and directs you to the PayPal documentation for instructions on obtaining a BAID via the PayPal APIs and sending that BAID to Zuora when creating a payment method.
PayPal Billing Agreement IDs
A billing agreement ID (BAID) is specific to the PayPal payment method and BAID is a contract that allows a merchant to withdraw funds from a customer's PayPal account without the customer having to log into PayPal to approve each and every payment transaction. Billing agreements are typically used for recurring payments, but can be used to pay for one time charges as well. BAIDs do not expire and are good until the BAID is canceled by the customer. The funding source for a BAID is either a credit card or a bank account. The BAID information stored in Zuora is the BAID number and the PayPal email address for the customer. Therefore, no secure information related to the funding source (such as credit card numbers or bank account numbers) are stored in Zuora.
PayPal Express Checkout
Using the Express Checkout APIs, you can create a BAID that gets passed to Zuora to create the payment method. The Express Checkout documentation for each of the PayPal products is available on the PayPal website.
- Payflow Pro
- Website Payments Pro Payflow Pro Edition
- Website Payments Pro (see PayPal Express Checkout Advanced Features Guide
- PayPal API Reference guide for Website Payments Pro and Express Checkout
- PayPal API Basics: SOAP and API Basics NVP
Sample Workflow for Using BAID
Here is a sample workflow for how a PayPal BAID gets created and stored in Zuora:
- 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.
- You initiate the creation of a billing agreement with PayPal, then redirect the end customer's browser to PayPal's site to accept the billing agreement. Once the billing agreement is accepted, the customer is directed back to your website to complete the purchase.
- The customer's acceptance of the billing agreement creates the PayPal billing agreement ID (BAID) that gets stored in Zuora as a payment method.
- The BAID 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 BAID in their Zuora customer account, without the customer having to log into PayPal again.
- You (the merchant) must be using PayPal Express Checkout, PayPal's Payflow Pro, Website Payments Pro Payflow Edition, or Website Payment Pro gateways with PayPal Express Checkout enabled.
- You must have reference transactions enabled for your PayPal merchant account. Billing Agreement IDs (BAIDs) are a type of reference transaction and reference transactions is a feature that must be enabled by PayPal on your merchant account. The process for enabling reference transactions by PayPal can take some time since the request goes through a vetting (underwriting) process. You can work with your PayPal account manager and/or call one of the following numbers to request the reference transaction feature be enabled in their live (production) PayPal account:
- US/CA: 1-888-221-1161
- UK: 08707 307 191
- Australia: 1-800-073-263
- Germany: 0180 500 66 27
- Other: 1-402-935-2080
- Prepare your Zuora tenant to:
- Use the PayPal Gateway.
- Accept PayPal as a payment method.
- Review the PayPal Express Checkout for Payflow Pro documentation for information on Reference Transactions and Billing Agreements (see Chapter 2) and the PayPal documentation for obtaining a BAID without a purchase (all documentation links are provided above under the PayPal Express Checkout section.
- Additional help information is available on PayPal's x.com site (search for Billing Agreement)
URLs for Testing and Production
If you would like to test our reference transactions and with obtaining the billing agreement ID using your PayPal Sandbox, you can request reference transaction for your PayPal Sandbox by posting a request to the PayPal x.commerce forum.
- When testing with a PayPal Sandbox, URLs should reference: https://www.sandbox.paypal.com.
- When using a PayPal live account, URLs should reference: https://www.paypal.com.
Testing your integration using a PayPal live account is recommended prior to fully going live with this BAID integration. If reference transactions is enabled in your PayPal Sandbox but is not enabled in your PayPal live account, your integration will not work. Reference transactions must be enabled for the account you want to use for creating BAIDs.
Two Ways to Obtain a BAID
There are two primary ways to obtain a BAID, listed below. Zuora uses method #2, obtaining a BAID without making a purchase through PayPal.
- The customer makes a purchase through PayPal's web site and the merchant retrieves a token used to create the BAID.
- The customer does not make a purchase through PayPal's website, rather they are making the purchase on your website. The customer will be briefly redirected to PayPal's web site to accept the billing agreement and directed back to your website to make a purchase using the PayPal (BAID) payment method. A token obtained during this process is used to create the BAID and to store the BAID in your Zuora customer account for recurring payments.
Below are the steps from an API integration perspective. We provide you a second method so you can see an alternative way of doing this. Please note that these instructions are from PayPal and PayPal should be your first line of support if you encounter any issues.
Example: Obtaining a BAID Without an Express Checkout Purchase for Website Payments Pro
These steps follow the PayPal Express Checkout Advanced Features Guide.
Step 1[Paypal NV API]: Call SetExpressCheckout
As a response to the above request, you receive a
Step 2 [Paypal NV API]: Redirect to PayPal with Token
Example redirect URL containing the
token from Step 1.
TOKEN to this URL and redirect the Customer to PayPal's site to accept the Billing Agreement. The customer will be asked to enter their PayPal credentials and once they successfully accept the billing agreement, the customer is redirected to the
RETURNURL value from Step 1.
Step 3 [Paypal NV API]: Call GetExpressCheckoutDetails
From the page that you specified in
RETURNURL, now call
GetExpressCheckoutDetails to get the
PAYERID of the buyer.
Token in this request and get back the billing agreement details such as the
Step 4 [Paypal NV API]: Call CreateBillingAgreement
Create Billing Agreement Request Token and Action = X.
PARTNER=partner &VENDOR=vendor &PWD=password
This will return a BAID that you will use to store in Zuora as a PayPal payment method.
Step 5 [Zuora API]: Add the BAID as a Payment Method
Make a call to Zuora to add the BAID as a payment method.
Importing Existing BAIDs into Zuora
If you would like to migrate BAIDs for existing customers in PayPal over to Zuora, so that Zuora can handle the recurring billing for such customer, simply follow the instructions for creating a payment method. You can use the billing agreement information such as the Billing Agreement ID number and the PayPal Email address to create the PayPal payment method in Zuora.
Create a PayPal Payment Method in API
When creating a Payment Method through the Zuora API, you can use the SOAP
create() call. For more information about the call, see create(). You can also use the REST API Create operation to create a Paypal BAID payment method.
The PayPal BAID payment method you create must have an account ID; the payment method account cannot be anonymous. You can also use the Zuora API to create a subscription with a PayPal BAID payment method using the
Follow the instructions to populate all the required payment method information and be sure to populate all the PayPal fields and payment method
PaypalBaid: This is the billing agreement number.
PaypalEmail: This is the PayPal email address associated with the billing agreement number.
PaypalType: Use ExpressCheckout (for Payflow Pro gateway) and use AdaptivePayments(for the PayPal Adaptive Payments gateway) when creating PayPal payment methods.
Type: For the type of payment method, choose PayPal.
Create a PayPal Payment Method in the UI
When creating a Payment Method in the Zuora UI, follow the instructions to create a payment method in the customer account.
PayPal payment methods can only be created if the customer account (under Billing and Payment Term) is set up to use PayPal as the gateway.
Once PayPal is set up as the Payment Gateway and attempt to create a new electronic payment method, you will see PayPal as an option with fields to enter a PayPal Email and the BAID.
PayPal Recurring Payments Profiles
If you have migrated any customer accounts from PayPal to Zuora which have active PayPal recurring payments profiles, you may need to disable the recurring profile in PayPal since recurring payments will now be handled in Zuora. Deactivating recurring payments profiles will avoid duplicate payments being charged to your customers (with one payment in PayPal and one payment in Zuora).
Deactivate a Recurring Payments Profile in the PayPal API and UI
To deactivate a recurring payments profile via the PayPal API, you will need to pass the action=C to cancel an active profile and provide the profileID in the request as shown here:
For more information, view the Payflow Pro Recurring Billing Guide.
To deactivate a recurring payments profile via the PayPal UI, go to https://manager.paypal.com and follow these steps:
- Go to Service Setting > Recurring Billing > Manage Profiles.
- On the next page you can do search by profile-id or all the active profiles.
- Click on Modify Profile Details button for the profile you wish to dectivate.
- Click deactivate.
For more information, log into https://manager.paypal.com and use the "help" feature to search for this topic (for example: search for cancelling recurring profile."