Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
This guide describes how to perform recurring payments transactions using the Payflow SDK.
It also describes how to manage recurring payments profiles through the merchant’s PayPal
account. Recurring Payments is a scheduled payment solution that enables you to
automatically bill the buyer at regular intervals – for example, a monthly fee of $42 for 36
months with an initial fee of $129.
Audience
This guide assumes that its users:
z Have PayPal accounts that have the ability to use Payflow credentials.
z Are experienced web or application developers or merchants offering recurring payment
z Have a background in payments services
Preface
solutions to their buyers on their websites
z Have experience with Express Checkout if billing the buyer’s PayPal account on a
recurring basis
Where To Go For More Information
For more information, see the following documentation, which is available on Developer
Central:
z Website Payments Pro Payflow Edition Developer’s Guide
z Express Checkout for Payflow Pro
Revision History
TABLE 1.1 Revision history
DateChanges
January 2010Updated Preface description of Recurring Payments users.
Payflow Recurring Payments Developer’s Guide5
Revision History
ABLE 1.1 Revision history
T
DateChanges
August 2009 Added an example of obtaining a TOKEN from the Set Express
March 2009First publication of Payflow Recurring Payments for credit cards
Checkout response to create a Recurring Payments profile for
billing a PayPal account.
and PayPal accounts on a recurring basis
6Payflow Recurring Payments Developer’s Guide
1
Recurring Payments Overview
Website Payments Pro Payflow Edition (Payflow) Recurring Payments allows you to bill a
buyer’s credit card or PayPal account for a fixed amount of money on a fixed schedule.
Consider the following examples:
z A buyer purchases a subscription to a magazine or newsletter from your site and agrees to
pay a monthly fee.
z A buyer agrees to pay an Internet Service Provider a one-time setup fee and a flat fee on a
semi-annual basis to host a website.
z A buyer agrees to an installment plan to purchase a high-ticket item.
These examples represent payment transactions that reoccur periodically and are for a fixed
amount. PayPal offers Payflow recurring payments with the Direct Payments (credit card
processing) and Express Checkout payment solutions.
N OTE: To use recurring payments to bill a buyer’s PayPal account, you must first establish a
billing agreement with the buyer through the Express Checkout flow. For details, see
the document entitled Express Checkout for Payflow Pro, which is available on
Developer Central.
About the Payflow Recurring Payment Services
When you create recurring payments for a buyer, you create a recurring payments profile. The
recurring payments profile contains information about the recurring payments, including
details for an optional trial payment period and a regular payment period. If the profile is for
billing the buyer’s credit card, it specifies the credit card account to bill and the expiration
date. A recurring payments profile also includes the associated contact information, the
amount to charge each time, the billing period (monthly, weekly, and so on), and the number of
payment periods over the life of the recurring billing agreement.
After a recurring payments profile is created, PayPal automatically queues payments based on
the billing start date, billing frequency, and billing amount, until the profile expires or is
canceled by the merchant.
After the recurring payments profile is created, you can view recurring payments details and
perform other recurring payments profile management tasks:
z Manually, by accessing your PayPal Business account
z Programmatically, by making calls to Payflow recurring payments requests
The following sections describe how to perform recurring payments profile tasks:
z “Creating Recurring Payments Profiles” on page 11
z “Deactivating and Reactivating Recurring Payments Profiles” on page 21
Payflow Recurring Payments Developer’s Guide7
Recurring Payments Overview
Managing Recurring Payments Profiles Through PayPal
z “Canceling Recurring Payments Profiles” on page 25
z “Getting Recurring Payments Profile Details” on page 29
z “Billing the Outstanding Amount” on page 33
z “Updating Recurring Payments Profiles” on page 35
Managing Recurring Payments Profiles Through PayPal
After you have created recurring payments profiles, you can manage them through your
PayPal Business account:
1. Log in to your business account.
2. Click the Recurring Payments link either in the Tools section of the Account Overview
page or on your Profile page.
The Recurring payments overview page appears, as shown below.
FIGURE 1.1 Recurring payments overview page
8Payflow Recurring Payments Developer’s Guide
Limitations
The current release of Payflow recurring payments has the following limitations:
z A recurring payments profile can have at most one optional trial payment period and a
single regular payment period.
z The recurring payments profile start date may not be earlier than the profile creation date.
Recurring Payments Terms
Table 1.1 lists commonly used terms related to Payflow Recurring Payments.
TABLE 1.1 Payflow Recurring Payments Terms
TermMeaning
PaymentThe amount that is transacted during each regular payment
Recurring Payments Overview
Limitations
period, not including shipping and tax. It is represented by the
Payflow AMT parameter. Payments differ from transactions.
Several transactions may be required to successfully perform a
payment for a payment period, for example, because of a lack of
funds during the first transaction attempts.
Regular payment periodThe period during which a single regular (non-trial) payment is
made. It is represented by the PAYPERIOD parameter. If, for
example, a $42 payment is due on a monthly basis, the regular
payment period is monthly.
Trial payment periodAn optional subscription period before the regular payment
period begins. It is represented by the TRIALPAYPERIOD
parameter. A trial payment period and trial payment may differ
from the regular payment period and regular payment.
TermThe total number of regular or trial payment periods. It is
represented by the TERM and TRIALTERM parameters. If there
are 36 monthly payments, for example, the term is 36. On the
PayPal website, term is called payment cycle.
Recurring payments profileYour definition of a recurring transaction for a single buyer. The
profile includes all information required to automatically bill the
right person the right amount per payment period over the billing
frequency.
Profile IDA 19-character string PayPal generates to uniquely identify a
recurring profile.
Outstanding balanceIf a payment fails for any reason, that amount is added to the
profile’s outstanding balance.
Payflow Recurring Payments Developer’s Guide9
Recurring Payments Overview
Recurring Payments Terms
10Payflow Recurring Payments Developer’s Guide
Creating Recurring Payments
2
Profiles
N OTE: The Payflow SDK recurring payments operations are available only to merchants who
have signed up for Payflow Recurring Payments.
Preparing to Create Recurring Payments Profiles
To set up recurring payments, you must collect all necessary information from the buyer
including the billing amount of the payment.
For recurring payments that you bill through the buyer’s credit card, this includes the buyer’s
credit card information.
For recurring payments that you bill through the buyer’s PayPal account, you must first call
the Set Express Checkout request, specifying the RecurringPayments billing type and
providing the billing description for one or more profiles that you want to create. For details,
see Express Checkout for Payflow Pro.
After you have collected the information, you can create the recurring payments profile either
through the PayPal website or programmatically using the PayPal SDK recurring payments
SDK operations.
Creating Profiles Through Your PayPal Account
To create a recurring payments profile through your PayPal Business account:
1. Log in to your business account.
2. Click the Recurring Payments link either in the Tools section of the Account Overview
page or on your Profile page.
The Recurring payments overview page appears, as shown in Figure 2.1 .
Payflow Recurring Payments Developer’s Guide11
Creating Recurring Payments Profiles
Creating Profiles Through Your PayPal Account
FIGURE 2.1 Recurring payments overview page
3. Click the Create a new profile link.
4. On the Create a Recurring Payment profile page, fill in all required information about the
buyer, and click continue.
If successful, the Review a Recurring Payment profile page appears.
5. Review the profile description. Click Update to edit, if necessary, or Cancel to cancel the
profile. Click Submit to create the profile.
Upon successful profile creation, you will receive a status message along with a summary
of the profile information, such as shown in Figure 2.2 .You can use the profile ID to locate
and obtain information about this profile in the future.
Click the Recurring Payments link either in the Tools section of the Account Overview page or
on your Profile page to view the Recurring payments overview page. From this page, you can
manage the profiles you create. For more information, see “Managing Recurring Payments
STARTStart date for the recurring payment. The date is tomorrow or a
date in the future.
TERMLife of the payment.
PAYPERIODHow often the payment occurs, such as weekly or twice a
month.
TOKENA TOKEN returned in the Set Express Checkout response.
Required for PayPal account billing only.
L_BILLINGAGREEMENTDESCR
IPTIONn
BA_DESCA single billing agreement description only; if
One or more billing agreement descriptions up to a maximum of
10. Required for PayPal account billing only.
L_BILLINGAGREEMENTDESCRIPTIONn is specified, it
overrides this value. Required for PayPal account billing if
L_BILLINGAGREEMENTDESCRIPTIONn is not specified.
Upon successful creation of a profile, PayPal activates the profile, initiates the billing cycle,
and returns a profile ID. Upon failure, PayPal does not generate the profile and, instead,
returns a status message.
As with all direct payments, PayPal is completely invisible to the buyer. The buyer’s credit
card statement will not indicate that PayPal processed the payment.
Options for Creating a Recurring Payments Profile
Programmatically
You have the following options when creating a recurring payments profile:
z Specifying the Regular Payment Period
z Including an Optional Trial Payment Period
z Specifying an Initial Payment
z Setting the Number of Failed Payments
14Payflow Recurring Payments Developer’s Guide
Options for Creating a Recurring Payments Profile Programmatically
Specifying the Regular Payment Period
Each recurring payments profile has a regular payment period that defines the amount and
frequency of the payment. Table 2.2 lists the required fields associated with creating the
regular payment period.
TABLE 2.2 Regular Payment Period Parameters
AMT
START
TERM
PAYPERIOD
Including an Optional Trial Payment Period
You can optionally include a trial payment period in the profile by specifying the following
fields in the request to create a profile. Table 2.3 lists the required fields if you are also
creating an optional trial payment period.
Creating Recurring Payments Profiles
N OTE: If you include any of the trial payment period parameters, you must include all them in
the request to create a recurring payments profile.
T
ABLE 2.3 Trial Payment Period Parameters
TRIALSTART
TRIALTERM
TRIALPAYPERIOD
TRIALAMT
TRIALFREIGHTAMT
TRIALTAXAMT
Specifying an Initial Payment
You can optionally specify an initial non-recurring payment when the recurring payments
profile is created by including the fields listed in Table 2.4 in the request to create a profile.
T
ABLE 2.4 Optional Initial Payment Parameters
OPTIONALTRXAMT
FAILEDINITAMTACTION
When you specify an amount for OPTIONALTRXAMT, the profile is billed for that amount
initially upon recurring payments profile creation. If you don’t supply a value for this
Payflow Recurring Payments Developer’s Guide15
Creating Recurring Payments Profiles
Example: Creating a Recurring Payments Profile For Billing a Credit Card
parameter, PayPal performs a $1.00 authorization using the merchant-supplied credentials to
create a recurring payments profile.
By default, PayPal will not activate the profile if the initial payment amount fails. You can
override this default behavior by setting FAILEDINITAMTACTION to ContinueOnFailure,
which indicates that if the initial payment amount fails, PayPal should add the failed payment
amount to the outstanding balance due on this recurring payment profile.
If FAILEDINITAMTACTION is not set or is set to CancelOnFailure, PayPal creates the
recurring payments profile but places it in a pending status until the initial payment is
completed. If the initial payment clears, this means PayPal activated the pending profile. If the
payment fails, PayPal did not activate it. To check the profile status, see “Obtaining Profile
Details Through Your PayPal Account” on page 30.
Setting the Number of Failed Payments
By including the optional MAXFAILEDPAYMENTS parameter in the request to create a profile,
you can set the number of failed scheduled payments allowed before PayPal deactivates
(suspends) the profile. By default, the value is 0, which means no limit.
Billing the Outstanding Amount
If a payment fails for any reason, the amount that was to be billed (including shipping and tax,
if applicable) is added to the profile’s outstanding balance. Use the
AUTOBILLOUTSTANDINGAMT
parameter field in the request to create a profile to specify whether or not the outstanding
amount should be added to the payment amount for the next billing cycle.
Example: Creating a Recurring Payments Profile For Billing a
Credit Card
The following Payflow parameter string creates a profile for credit card recurring payments
billing. Parameter fields required for creating the credit card recurring payments profile are in
boldface. The example includes the following:
z An initial non-recurring payment of $10.00
z Profile activation even if the initial payment amount fails
z A trial payment period starting August 2, 2009, for 2 months at a trial rate of $56.00 per
month plus $20.00 shipping and $2.50 tax
z A regular payment starting October 27, 2009, for 10 months at a rate of $60.00 per month
excluding shipping and tax
z The outstanding amount is added to the payment amount for the next billing cycle
(PAYPERIOD)
16Payflow Recurring Payments Developer’s Guide
Creating Recurring Payments Profiles
Example: Creating a Recurring Payments Profile For Billing a Credit Card
Example: Creating a Recurring Payments Profile For Billing a PayPal Account
Example: Creating a Recurring Payments Profile For Billing a
PayPal Account
To create a Recurring Payments profile for a PayPal account, you must call Set Express
Checkout and pass the following parameter information:
z The billing type value RecurringPayments (required)
z A description of the goods or services associated with the agreement (required)
The example below passes the billing type and descriptions for two billing agreements. The
parameters required to create the Recuring Payments profile are in boldface.
Set Express Checkout Request
"TRXTYPE=A
&USER=User
&TENDER=P
&PARTNER=PayPal
&VENDOR=Vendor
&PWD=Pwd
&ACTION=S
&AMT=10.00
&RETURNURL=http://...
&CANCELURL=http://...
&CURRENCY=USD
&L_BILLINGTYPE0=RecurringPayments
&L_BILLINGAGREEMENTDESCRIPTION0=Time magazine
&L_BILLINGTYPE1=RecurringPayments
&L_BILLINGAGREEMENTDESCRIPTION1=Newsweek magazine
&SHIPTOCITY=San Jose
&SHIPTOCOUNTRY=USA US
&SHIPTOSTATE=CA
&SHIPTOSTREET=1 Main St
&SHIPTOZIP=95131
&PAYMENTTYPE=any"
When creating the recurring payments profile with ACTION=A, you pass the TOKEN returned in
the Set Express Checkout response, along with the following parameters:
z The L_BILLINGAGREEMENTDESCRIPTIONn string (exactly as it was passed in the call to
Set Express Checkout) for the profile you want to create
z TENDER type P to identify the recurring payments as billing a PayPal account
z The TOKEN returned in the Set Express Checkout response
18Payflow Recurring Payments Developer’s Guide
Creating Recurring Payments Profiles
Example: Creating a Recurring Payments Profile For Billing a PayPal Account
The following example creates a recurring payments profile that bills a PayPal account.
Parameters required for creating the PayPal account recurring payments profile are in
boldface. The example allows four failed scheduled payments before PayPal deactivates the
profile.