Table of contents
- 1. Overview --- IN PROGRESS
- 2. Solution
- 3. Prerequisites
- 4. 2 Ways to Obtain a BAID
- 5. Obtaining a BAID Without an Express Checkout Purchase
- 5.1. Method 1: Using PayPal Payflow Pro APIs (Recommended)
- 5.1.1. Step 1 [Payflow API]: Create Buyer Billing Agreement Request
- 5.1.2. Step 2 [Payflow API]: Redirect Customer to PayPal Site with a Token
- 5.1.3. Step 3 [Payflow API]: Get the Billing Agreement Details
- 5.1.4. Step 4 [Payflow API]: Create Customer Billing Agreement
- 5.1.5. Step 4 [Payflow API]: Authorize or Capture a transaction by passing the BAID returned from Create Billing Agreement call (step 3) with no interaction from the customer.
- 5.1.6. Step 5 [Zuora API]: Add the BAID as a Payment Method
- 5.2. Method 2: Using PayPal API and PayPal NV API
- 5.1. Method 1: Using PayPal Payflow Pro APIs (Recommended)
- 6. Importing Existing BAIDs into Zuora
- 7. PayPal Recurring Payments Profiles
- 8. Related
- 1. Overview --- IN PROGRESS
- 2. Solution
- 3. Prerequisites
- 4. 2 Ways to Obtain a BAID
- 5. Obtaining a BAID Without an Express Checkout Purchase
- 5.1. Method 1: Using PayPal Payflow Pro APIs (Recommended)
- 5.1.1. Step 1 [Payflow API]: Create Buyer Billing Agreement Request
- 5.1.2. Step 2 [Payflow API]: Redirect Customer to PayPal Site with a Token
- 5.1.3. Step 3 [Payflow API]: Get the Billing Agreement Details
- 5.1.4. Step 4 [Payflow API]: Create Customer Billing Agreement
- 5.1.5. Step 4 [Payflow API]: Authorize or Capture a transaction by passing the BAID returned from Create Billing Agreement call (step 3) with no interaction from the customer.
- 5.1.6. Step 5 [Zuora API]: Add the BAID as a Payment Method
- 5.2. Method 2: Using PayPal API and PayPal NV API
- 5.1. Method 1: Using PayPal Payflow Pro APIs (Recommended)
- 6. Importing Existing BAIDs into Zuora
- 7. PayPal Recurring Payments Profiles
- 8. Related
Overview --- IN PROGRESS
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 payment method must utilize the PayPal Payflow APIs to create the PayPal Billing Agreement ID (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 walks you through two different methods of retrieving the BAIDs from Paypal, one method uses the Payflow Pro APIs only (recommended) and the second method uses both the PayPal NVP API and the PayPal Payflow Pro API. Once you have obtained the BAID via the PayPal APIs, you can pass it to Zuora via the Zuora API to create the payment method. The methods described here are only examples and users should work with PayPal for any specific questions related to their APIs.
PayPal Billing Agreement IDs
A billing agreement ID (BAID) is specific to the PayPal payment method and the 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
Does a merchant have to enable express checkout to use BAID PayPal payment method? Why do the Payflow docs (in Step 1) use a SetExpressCheckout call instead of SetBillingAgreement call? Jason says the SetBillingAgreement (Action = Z) is specific to Payflow API, however, this x.com article gives an example of how this is done using Payflow APIs and it also calls SetExpressCheckout (Action = S) first: https://www.x.com/node/2759.
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 a 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.
Solution
Prerequisites
- You (the merchant) must be using 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 both 1) use the PayPal Gateway and 2) 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 obtaining a BAID without a purchase (see page 20).
- 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.
2 Ways to Obtain a BAID
There are two primarily different ways to obtain a BAID:
- 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 biilling 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 store the BAID in your Zuora customer account for recurring payments.
The methods described below are for the latter use case, when you obtain a BAID without making a purchase through Paypal. Below are the steps from an API integration perspective. We provide you two methods of obtaining the BAID and creating a payment method in Zuora, and the first method is recommended. 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.
[Will the instructions for Method 1 work for Payflow Pro BYOB, WPP 2.0 and WPP 3.0 customers? If yes, then we can just provide 1 method (the recommended one) in these instructions, rather than 2 methods).
Obtaining a BAID Without an Express Checkout Purchase
Method 1: Using PayPal Payflow Pro APIs (Recommended)
Recommended method since it uses only one type of API, the Payflow Pro APIs which Zuora uses to integrate with all PayPal products.
Refer to PayPal documentation on Billing Agreements and how to obtain a BAID without a purchase (Chapter 2, page 20+) for more information.
[Why isn't the first step to SetExpressCheckout - that's what it says in the Express Checkout Payflow API docs pg. 26? Can merchants obtain a BAID without purchase without SetExpressCheckout?]
Step 1 [Payflow API]: Create Buyer Billing Agreement Request
In this step, you will use the SetBillingAgreement request (ACTION=Z) to obtain the BAID. This involves redirecting the customer to PayPal's website to accept the billing agreement, and once completed, PayPal provides a token in the response. This token will be used for subsequent steps.
Request:
PWD=%PASSWORD%
&USER=%USER%
&VENDOR=%VENDOR%
&PARTNER=%PARTNER%
&CURRENCY=USD
&TENDER=P
&ACTION=Z
&CUSTOM=CustomMessage
&TRXTYPE=A
&CANCELURL=http://www.yourcancelurl.com/
&RETURNURL=http://www.yourreturnurl.com/
&BA_DESC=testBAdescription
&BILLINGTYPE=MerchantInitiatedBilling
&BA_CUSTOM=bacustom
&PAYMENTTYPE=any
Response:
RESULT=0
&RESPMSG=Approved
&TOKEN=BA-4MG198371G6377215
&CORRELATIONID=5cdda7e67a332Step 2 [Payflow API]: Redirect Customer to PayPal Site with a Token
Append 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.
https://www.paypal.com/cgi-bin/webscr?cmd=_customer-billing-agreement&token=BA-4MG198371G6377215
Note:
cmd=_customer-billing-agreementin the redirect URL is not required and can be removed.
Step 3 [Payflow API]: Get the Billing Agreement Details
From the page that you specified in RETURNURL, you will now send the Token in this request and get back the billing agreement details such as the PAYERID and EMAIL (you have th option of storing this information).
Request:
PWD=%PASSWORD%
&USER=%USER%
&VENDOR=%VENDOR%
&PARTNER=%PARTNER%
&TRXTYPE=A
&TENDER=P
&ACTION=W
&TOKEN=BA-4MG198371G6377215
Response:
RESULT=0
&RESPMSG=Approved
&TOKEN=BA-4MG198371G6377215
&PAYERID=QWC946C64HLEU
&CORRELATIONID=199e47b7cb48f
&EMAIL=mike@thecustomer.com
&PAYERSTATUS=verified
&FIRSTNAME=Mike
&LASTNAME=Customer
&SHIPTOBUSINESS=pMiNd Sandbox
&COUNTRYCODE=USStep 4 [Payflow API]: Create Customer Billing Agreement
Now call Create Billing Agreement Request Token and Action = X. Using ACTION=X, you will now get a response with a BAID that you can store in Zuora as a PayPal payment method.
Request:
PWD=%PASSWORD%
&USER=%USER%
&VENDOR=%VENDOR%
&PARTNER=%PARTNER%
&TRXTYPE=A
&TENDER=P
&ACTION=X
&TOKEN=BA-4MG198371G6377215
&PAYERID=QWC946C64HLEU
Response:
RESULT=0&PNREF=E18P0F8D438E&RESPMSG=Approved&TOKEN=BA-4MG198371G6377215&PAYERID=QWC946C64HLEU&CORRELATIONID=8ec18025818ee
&BAID=B-5AW87276MG422713PStep 4 [Payflow API]: Authorize or Capture a transaction by passing the BAID returned from Create Billing Agreement call (step 3) with no interaction from the customer.
PWD=%PASSWORD%
&USER=%USER%
&VENDOR=%VENDOR%
&PARTNER=%PARTNER%
&TRXTYPE=S&TENDER=P
&ACTION=D
&CAPTURECOMPLETE=NO
&BAID=B-5AW87276MG422713P
&AMT=500.00 Response:
RESULT=0
&PNREF=E18P0F8D48EB
&RESPMSG=Approved
&PPREF=4GK54199J10230343
&CORRELATIONID=bd6312879054a
&FEEAMT=14.80
&BAID=B-5AW87276MG422713P
&PAYMENTTYPE=instant
&PENDINGREASON=completed[Can the above step 4 be removed and replace it with the step 5 below? I think so.]Step 5 [Zuora API]: Add the BAID as a Payment Method
Method 2: Using PayPal API and PayPal NV API
Step 1[Paypal NV API]: Call SetExpressCheckout
USER=APIUsername
&PWD=APIPassword
&SIGNATURE=APISig
&VERSION=62.0
&METHOD=SetExpressCheckout
&PAYMENTREQUEST_0_PAYMENTACTION=Sale
&AMT=0.00
&RETURNURL=http://www.paypal.com
&CANCELURL=http://www.paypal.com
&BILLINGTYPE=MerchantInitiatedBilling
As a response to the above request, you will get back a token.
Step 2 [Paypal NV API]: Redirect to PayPal with Token
Example redirect URL containing the token from Step 1.
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-11J57721ES824652J
Append 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.
Send the Token in this request and get back the billing agreement details such as the PAYERID and EMAIL (you have th option of storing this information).
Step 4 [Paypal Payflow API]: Call CreateBillingAgreement
Now call Create Billing Agreement Request Token and Action = X.
PARTNER=partner &VENDOR=vendor &PWD=password
&USER=user
&TRXTYPE=A
&ACTION=X
&TENDER=P &TOKEN=EC-36X58962RS656712N
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
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 in the Zuora API, use the create() call. Follow the instructions to populate all the required payment method information and be sure to populate all the PayPal fields and payment method Type.
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
API
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:
TRXTYPE=R&TENDER=C&PARTNER=<wbr/>PayPal&VENDOR=Acme&USER=Acme&<wbr/>PWD=a1b2c3d4&ACTION=C&<wbr/>ORIGPROFILEID=RP000000001234.
For more information, view the Payflow Pro Recurring Billing Guide.
UI
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."
Related
- Payment Method
- Zuora offers three payment method options: Z-Payment Method, External Payment Method, or None. See Payment Methods for more information.
- Configure Payment Method Retry Rules
- Zuora allows you to retry payments on a scheduled basis by using scheduled payment runs which will process any invoices that have not been fully paid for customers who have auto-pay enabled. You can also specify the maximum number of consecutive times a failed payment method (for example, credit card) is retried for payment, as well as the ability to define a time period to not retry a payment. For instance if you define the interval as 8 hours, an automated payment retry will not attempt a payment if the last failed payment was less than 8 hours ago.
- Payment Methods
- The payment method refers to the form of payment customers are using. For online purchases, they usually take the form of electronic payments like credit cards, debit cards, bank transfers, third-party processors (such as Paypal), or non-electronic payments like checks and cash. The customer's method of payment can be created and edited in the customer account. To learn more, and to configure payment methods, see Define Payment Methods.
- Supported Payment Methods
- This topic describes the payment methods supported by the payment gateways. Empty fields in the tables indicate that the payment method is not supported by that payment gateway.
- Direct Debit for GlobalCollect
- Direct debit is a way of collecting funds for a payment directly from a customer’s bank account. It is a very common method of payment in many countries and is frequently used for payment of utilities (such as telephone bills) or mortgage which occur on a recurring basis.
- Implementing Direct Debit with GlobalCollect
- Although direct debit is treated like any other electronic payment method in Zuora, there are additional steps that you need to perform to implement this payment method. These topics provide an overview of implementing and managing direct debit transactions using the Zuora-GlobalCollect integration. During your integration please contact your GlobalCollect integration manager or Zuora Global Support for assistance.Your GlobalCollect integration manager will provide you documentation and guides to implement direct debit for the specific countries you want to support. For example, direct debit in the United Kingdon has different rules and regulations than direct debit in Germany.
- Direct Debit Mandates
- Unlike credit cards, you (the merchant) must obtain authorization from your customers to debit their bank account for payment. This authorization can be a confirmation page on the your web store in which authorization is confirmed by your customer when they accept your stated terms and conditions. Alternatively, the authorization can be provided using a signed agreement called a mandate.
- Obtaining and Processing Mandates
- Mandates are obtained and maintained by you (the merchant) and not by Zuora or your payment services provider, GlobalCollect. The mandate information along with your customer’s bank account information is submitted to GlobalCollect with each payment transaction request.
- Retaining Mandates
- You, the merchant, are required to keep a mandate up to date for as long as you continue to debit your customer’s account.
- Customer Notifications for Direct Debit
- Some countries require you, the merchant, to provide the customer with advance notice before debiting the customer's account for payment, while other countries may not require it but consider it a best practice. Advance notice is especially important when the recurring fees have changed, for example, the customer purchased an additional product this month.
- Setting Up a Payment Method for a Customer Account (Beginner)
- Authorize.net Gateway (Intermediate)
- Chase Paymentech Orbital Gateway (Salem Platform) (Intermediate)
- Chase Paymentech Spectrum (Intermediate)
- CyberSource Payment Gateway (Intermediate)
- Litle Payment Gateway (Intermediate)
- PayPal Adaptive Payments (Intermediate)
- PayPal Payflow Pro, Website Payments Payflow Edition, Website Pro Payment Gateway (Intermediate)
- Logging In to the Zuora System (Intermediate)
- Selecting and Signing up for a Payment Gateway
- How do I add custom fields to my WSDL?
- How do I allow customers to modify their stored payment methods?
- How do I bill a customer for a new purchase without using the default payment method in the API?
- How do I capture the SOAP API Request and Response?
- How do I choose a payment gateway?
- How do I control when Zuora will authorize the Payment Method?
- How do I handle ACH or Direct Debit payments that are reversed?
- How do I migrate my credit card data from my payment gateway to Zuora?
- How do I prevent my API user login from expiring?
- How do I prevent session tokens from expiring in the API?
- How do I set up a PCI compliant page to accept new payment methods?
- How do I use the credit card reference transaction payment method in Zuora?
- How do I use Zuora with my existing website?
Comments