Skip to main content

How do I use the credit card reference transaction payment method for PayPal in Zuora?

Zuora

How do I use the credit card reference transaction payment method for PayPal in Zuora?

Overview

Zuora supports electronic payment processing using a variety of different payment methods such as credit cards, debit cards, and direct debit (including ACH). For PayPal, Zuora also supports two payment methods based on PayPal reference transactions: Billing Agreement IDs (BAID) and Credit Card (CC) Reference Transactions. This article walks you through how to use credit card reference transactions as a payment method in Zuora, and discusses how to migrate CC reference transaction data from PayPal to Zuora.

Reference Transactions and Payment Tokenization

Reference transaction are payment transactions that utilize a transaction ID from a previously authorized transaction to process a subsequent payment. The transaction ID is a token that replaces sensitive payment method information (for example, a credit card or a bank account number) so the transaction ID/token is stored in Zuora as the payment method in place of sensitive card data or bank account information. Some payment gateways refer to the use of a prior authorized transaction to process another transaction as payment tokenization, but PayPal refers to this as a reference transaction. PayPal has two types of reference transactions: credit card reference transactions and billing agreement IDs (BAIDs). 

The use of reference transactions or tokenization reduces the PCI scope for merchants who are concerned about storing credit card data. Merchants using Zuora to store all credit card data do not necessarily need tokenization since Zuora manages all the PCI Compliance required of merchants handling sensitive credit card information within our application. 

PayPal Credit Card (CC) Reference Transactions

Zuora supports CC Reference Transaction payment methods for PayPal Payflow, Website Payments Pro Payflow Edition, and Website Payments Pro gateways. More information on how to use this payment method are provided in the solution below. 

PayPal Billing Agreement IDs (BAIDs)

A billing agreements ID (BAID) is specific to the PayPal payment method and the BAID is a contract that allows a merchant to withdraw funds from a customers PayPal account without the latter having to log into PayPal to approve and complete the transaction. 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) is stored in Zuora. See "How do I use the PayPal (BAID) payment method in Zuora?" for more information.

Solution

Prerequisites

  • You (the merchant) must be using PayPal's Payflow Pro, Website Payments Pro Payflow Edition, or Website Payment Pro gateways.
     
  • You must have reference transactions enabled for your PayPal 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 a 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

 

URLs for Testing and Production

If you would like to test reference transactions using your PayPal Sandbox, you can request reference transactions for your PayPal Sandbox.

Create a CC Reference Transaction Payment Method in the API and UI

API

When creating a CC reference transaction 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 CreditCard fields and payment method Type.

  • CreditCard: Fields include (but is not limited to) CreditCardExpirationMonth,  CreditCardExpirationYear, CreditCardHolderNameCreditCardNumber, CreditCardType, CreditCardSecurityCode (optional).
  • PaypalType: Choose ExpressCheckout (this is for Payflow Pro gateway) when creating credit card reference transaction payment methods.
  • Type: This is the type of payment method, you would choose CreditCardReferenceTransaction.

UI

When creating a CC reference transaction 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 attempts to create a new electronic payment method, you will see CC Reference Transaction as an option with fields to enter the credit card information. 

Once you have entered the credit card information required for the CC Reference Transaction payment method, save the information. 

Although credit card details were entered to create the payment method, Zuora calls the PayPal API to obtain a token (based on an Authorization ID) that is used to create the CC Reference Transaction payment method in Zuora. All future payments using this payment method are based off of the token rather than the credit card details. 

Refunds for CC Reference Transactions

The integration currently does not support refunds for payments using cc reference transactions. Refunds should be issued within the PayPal virtual terminal and reflected in Zuora as an external refund. 

Migrating PayPal CC Reference Transactions to Zuora

If you have existing customers with credit card information stored in PayPal, you can migrate their payment method information over to Zuora so that Zuora can process future recurring payments for such customer(s). If you are not able to obtain the full credit card information (such as credit card number, expiration date) in order to import the data into Zuora, you can instead export the previous transaction IDs from PayPal to create a CC Reference Transaction payment method in Zuora. Migrating your CC reference transaction IDs into Zuora allows your company to continue processing payments for your existing credit card customers without having to migrate over their actual credit card information.

Here's how it works (assuming you have met the prequisites above and have reference transactions enabled in your PayPal account):

  1. Extract the transaction/authorization IDs from manager.paypal.com.
  2. Prepare a migration file with the required information (see below). 
  3. Work with Zuora Professional Services to migrate these IDs into Zuora as payment methods. Zuora has an internal migration tool that creates the customer account, payment methods, and subcriptions from a prepared csv file. 
  4. Once step 3 is complete, you can process recurring payments using the stored CC Reference Transaction payment method in Zuora.
    • If you have enabled a PayPal recurring payments profile for this customer, you may need to deactivate the recurring payments profile (see below for more information) before processing a payment in Zuora to avoid charging your customer duplicate payments.

CC Reference Transaction IDs: PNREF and PPREF

Once you have processed a credit card transaction for your customer in PayPal, that transaction creates a PayPal transaction ID. This transaction ID can be used to initiate another Payment Method Verification or Sale transaction either in PayPal or Zuora; this type of transaction is called a CC reference transaction.

There are two types transaction IDs that can be migrated to Zuora and used for CC reference transactions: PNREF and PPREF. PNREF and PPREF are both unique transactions IDs, however, the difference in the pre-pending of the ID Names (PN vs PP) is based on the processor used: 

  • PNREF - Used for the Payflow Pro BYOB product for which a 3rd party (non-PayPal) is the payment processor is used with the gateway.
  • PPREF - Used for Website Payments Pro Payflow Edition and Website Payments Pro products for which PayPal is the payment processor. 

PNREF and PPREF IDs Expire

PNREF and PPREF IDs expire 1 year from the original transaction date from which the ID was created. Zuora peforms an auto-refresh of PNREF IDs stored in our application, however, the PPREF IDs are not automatically refreshed and require action from you (the merchant) to ensure the payment method is kept updated. 

Zuora Auto-Refresh of PNREF

Zuora has a daily scheduled auto-refresh process which executes at 3:00 am PT. This process looks for PNREFs approaching expiration and performs an authorization call to PayPal to retrieve an updated PNREF ID that will be valid for another year. The payment method is updated with the new PNREF ID number. 

Obtain Credit Card Information When PPREF Expires

The migration file (discussed below) used to import PNREF and PPREFs contains a column called "Trans_Time." This column contains the date timestamp of when the transaction ID was created (format: 2/25/2011 2:17:00 PM). You can use this file to keep track of PPREF IDs approaching expiration and implement a process to obtain credit card information from the customer so you can store a credit card payment method in Zuora. You have the option of requesting credit card information from your customer at any time, however, we recommend making this request before their PPREF expiration date. 

Extracting PNREF and PPREF IDs from PayPal

PNREF can be extracted from https://manager.paypal.com (see the Transaction ID column) while PPREFs can be extracted from your PayPal.com account. 

Preparing the Migration File 

A .CSV formatted file is used to load the customer accounts, contacts, subscriptions, and payment method information (including the CC reference transaction ID) into your Zuora tenant. Here is an example of what the finished csv migration file looks like and the information included on such file: 

Sample CCREfTxFileforPNREF.jpg

 

Sample CCREfTxFileforPPREF.jpg

Fields on the Migration File

Column (Field) Name

Required (Yes/No - Optional)

Value Description

 Sample Value

PROFILE_NAME

No

PayPal account name, must be a mailbox format.

melanie123@zuora.com

PROFILE

No

PayPal Recurring Profile ID

RP000000001234

STATUS

N

Zuora customer account status, set this to "Active."

Active

EXP_DATE

Yes

Payment method credit card expiration date (format: mmyy). For 01/2014, use 114

114
 

AMT

Yes

Subscription Rate Plan Charge Price

20

FREQUENCY

No

Billing Frequency of Subscription Rate Plan Charge

Month

START_DATE

Yes

Subscription Term Start Date (format: mm/dd/yyyy)

 3/4/2011

DATE_EST

Yes

Subscription Contract Effective Date (format: mm/dd/yyyy)

3/4/2011

FIRST_NAME

Yes

Stored as the Bill To/Sold To Contact First Name and the Credit Card Holder First Name

John

LAST_NAME

Yes

Stored as the Bill To/Sold To Contact Last Name and the Credit Card Holder Last Name

Doe

STREET

No

Stored as the Bill To/Sold To Contact Street Address

3400 Bridge Parkway

CITY

No

Stored as the Bill To/Sold To Contact City

Redwood City

STATE

Yes if Country = US or Canada

Stored as the Bill To/Sold To Contact State (format: state code)

CA for California

ZIP

No

Stored as the Bill To/Sold To Contact Zip Code

94065

COUNTRY

Yes

Stored as the Bill To/Sold To Contact Country (format: country code)

US for United States

TELEPHONE

No

Stored as the Bill To/Sold To Contact Phone Number

(650) 123-4567

EMAIL

Yes

Stored as the Zuora Customer Account Name and the Bill To/Sold To Contact Email Address, must be a mailbox format.

johndoe@zuora.com

NEXT_PAYMENT

No

Date of the next recurring payment in PayPal, we recommend leaving this blank. 

3/4/2011

TRANS_TIME

Yes

Last payment transaction date timestamp recorded in PayPal gateway, also when the credit card reference transaction ID was created. This is extracted from PayPal. (format: MM/DD/YYY hh:mm:ss PM/AM). Reference Transaction IDs are valid for 1 year from this date.

2/25/2011 2:17:00 PM

TRANS_ID

Yes

Credit card reference transaction ID (PNREF or PPREF). No spaces between characters for the ID. see above screenshot for example of how this looks in the file.
 

For PNREF, sample value for input file is:

VADE0B248932

or

For PPREF, sample value for input file is:

PPREF:68W3371331353001F

RESULT

Yes

0 (must be “0” for this import)

0

PRODUCT_SKU

Yes

Subscription product SKU, must be a valid SKU in the Zuora product catalog

SKU-00000059

RATE_PLAN_NAME

Yes

Subscription product rate plan name, must be a valid product rate plan name in the Zuora product catalog

Ultimate Screen Capture - Monthly

CREDIT_CARD_NUMBER

No

Masked credit card number that corresponds to the credit card used for reference transaction

4111XXXXXXX1111

CRM_ACCOUNT_ID

No

CRM Account ID for Salesforce or other CRM application

0018000000RA3jO

Loading the Migration File

Zuora Professional Services must be engaged to load the migration file into Zuora using an internal migration tool. Here are some tips to help ensure the file is successfully loaded: 

  • Make sure all required fields are populated.
  • The PRODUCT_SKU and RATE_PLAN_NAME must match a product SKU and rate plan name in your product catalog. A  sucessful upload will create the customer account, payment method, contact, and subscriptions. The subscription is created with the specified product rate plan charge, therefore, if the product or rate plan does not exist in your product catalog, an error will occur causing the upload to fail.
  • Make sure the dates are formatted as specified in the table above. If using MS Excel on a Mac to prepare the file, save the file using Windows CSV format. Malformatted dates may not prevent the record from being uploaded, but will be displayed incorrectly in the payment method. For example, the CC Reference Transaction may display a credit card expiration date of 05/513 rather than 05/2013.

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:

  1. Go to Service Setting > Recurring Billing > Manage Profiles.
  2. On the next page you can do search by profile-id or all the active profiles.
  3. Click on Modify Profile Details button for the profile you wish to deactivate.
  4. 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."