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.
Example: Creating a Recurring Payments Profile For Billing a PayPal Account
20Payflow Recurring Payments Developer’s Guide
Deactivating and Reactivating
3
Recurring Payments Profiles
You can deactivate (suspend) and reactivate recurring payments profiles as a service to buyers
who would like to have their billing suspended while away on vacation, for example.
N OTE: The Payflow SDK does not support canceling (terminating) recurring payments
profiles programmatically. You must cancel a profile on the PayPal website. For
details, see Chapter 4, “Canceling Recurring Payments Profiles.”
Deactivating a Profile Through Your PayPal Account
To deactivate a profile through your PayPal account:
1. Log in to your PayPal account.
2. Click the Recurring Payments link either in the Tools section in the Account Overview
page or on the Profile page.
3. On the Recurring payments overview page that appears, browse for the profile.
4. In the search results, click the profile Details.
The Recurring Payments Profile Details page appears.
5. In the Profile Status section (shown in Figure 3.1 ), click Suspend to deactivate the
recurring payments profile.
Payflow Recurring Payments Developer’s Guide21
Deactivating and Reactivating Recurring Payments Profiles
Reactivating a Profile Through Your PayPal Account
FIGURE 3.1 Profile Status section of Recurring Payments Profile Details page
6. The Suspend a recurring payment profile page appears.
7. Click Suspend to deactivate the profile or Cancel to cancel the action.
Reactivating a Profile Through Your PayPal Account
To reactivate a deactivated (suspended) profile through your PayPal account:
1. Log in to your PayPal account.
2. Click the Recurring Payments link either in the Tools section of the Account Overview
page or on the Profile page.
3. On the Recurring payments overview page that appears, browse for the profile.
4. In the search results, click the profile Details.
The Recurring Payments Profile Details page appears.
5. In the Profile Status section, click Reactivate to reactivate the recurring payments profile.
The Review a recurring payment profile page appears.
22Payflow Recurring Payments Developer’s Guide
Deactivating and Reactivating Recurring Payments Profiles
6. Click Submit to reactivate the profile or Cancel to cancel the action.
Upon successful reactivation, the Reactivate a profile page displays the message
confirming profile reactivation.
Deactivating a Profile Programmatically
You can deactivate a recurring payments profile programmatically using the Payflow SDK.
Table 3.1 lists the parameters required in a request to deactivate a profile. Provide values for
the following parameters. The ACTION value is always C.
TABLE 3.1 Parameters Required to Deactivate a Profile
ParameterNotes
TRXTYPEThe value R for recurring payments.
TENDERThe value C for credit card or P for PayPal.
Deactivating a Profile Programmatically
ACTION=CThe value C for deactivating a recurring payments profile.
ORIGPROFILEIDProfile ID of the profile to deactivate.
Reactivating a Profile Programmatically
You can reactivate a recurring payments profile programmatically using the Payflow SDK.
Table 3.2 lists the parameters required in a request to reactivate a profile. Provide values for
the following parameters. The ACTION value is always R.
ABLE 3.2 Parameters Required to Reactivate a Profile
T
ParameterNotes
TRXTYPEThe value R for recurring payments.
TENDERThe value C for credit card or P for PayPal.
ACTIONThe value R for reactivating a recurring payments profile.
ORIGPROFILEIDProfile ID of the profile to reactivate.
Example of Deactivating a Profile
The following example request deactivates (suspends) a profile.
Payflow Recurring Payments Developer’s Guide23
Deactivating and Reactivating Recurring Payments Profiles
You cancel (terminate) a profile by browsing for it from the Recurring Payments Overview
page on the PayPal website and manually canceling it, as described below.
N OTE: You cannot cancel recurring payments profiles programmatically.
Canceling Recurring Payments Profiles Through Your PayPal
Account
To cancel a recurring payments profile:
1. Log in to your PayPal 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 4.1 .
FIGURE 4.1 Recurring payments overview page
3. Click the Browse for profiles link. Alternately, if you know the profile ID of the profile you
want to cancel, click the Search for profiles by ID link.
Payflow Recurring Payments Developer’s Guide25
Canceling Recurring Payments Profiles
Canceling Recurring Payments Profiles Through Your PayPal Account
4. In the search results, click the profile Details.
The Recurring Payments Profile Details page appears.
5. In the Profile Status section of the page (shown in Figure 4.2 ), click Cancel to cancel the
profile.
FIGURE 4.2 Profile Status section of Recurring Payments Pofile Details page
You are prompted to confirm canceling the profile. Upon confirmation, the Profile Status
History page appears (see Figure 4.3 ) showing the status history of the profile.
26Payflow Recurring Payments Developer’s Guide
Canceling Recurring Payments Profiles Through Your PayPal Account
FIGURE 4.3 Profile Status History page
Canceling Recurring Payments Profiles
Payflow Recurring Payments Developer’s Guide27
Canceling Recurring Payments Profiles
Canceling Recurring Payments Profiles Through Your PayPal Account
28Payflow Recurring Payments Developer’s Guide
5
Getting Recurring Payments
Profile Details
You can request to get details of a profile. Along with the information that you specified in the
request, a successful response returns the following summary information:
z Subscriber’s name
z Profile status
z Number of billing cycles as defined by PAYPERIOD completed during the current active
billing period
z Number of payments left to be billed
z Current outstanding balance
z Total number of failed payments
z Amount of the last successful payment received
z Last four digits of the buyer’s credit card number for credit card recurring billing
N OTE: Only the last 4 digits of the credit card account number are returned and CVV2 is never
returned.
Profile Status
A recurring payments profile can have one of the following status values:
z ACTIVE
z PENDING
z DEACTIVATED BY MERCHANT (profile is suspended)
z PROFILE TERMINATED (profile is canceled)
z EXPIRED
To view the status of a profile, see “Obtaining Profile Details Through Your PayPal Account.”
If the profile is successfully created, its status is ACTIVE. If, however, a non-recurring initial
payment fails and the FAILEDINITAMTACTION parameter is set to CancelOnFailure in the
request to create the profile, the profile is created with a status of PENDING until the initial
payment either completes successfully or fails.
You can reactivate a deactivated (suspended) profile. See Chapter 3, “Deactivating and
Reactivating Recurring Payments Profiles,” for details.
You can cancel (terminate) a profile through your PayPal account. See Chapter 4, “Canceling
Recurring Payments Profiles,” for details.
Payflow Recurring Payments Developer’s Guide29
Getting Recurring Payments Profile Details
Obtaining Profile Details Through Your PayPal Account
A profile has a status of EXPIRED when the total billing cycles for the optional trial payment
period and the regular payment period have been completed.
Obtaining Profile Details Through Your PayPal Account
To obtain details of a profile through your PayPal account:
1. Log in to your PayPal Business account.
2. Click the Recurring Payments link either in the Tools section of the Account Overview
page or on your Profile page.
3. On the Recurring payments overview page, browse for the profile.
4. In the search results, click the profile Details.
The Recurring Payments Profile Details page appears.
5. In the Profile Status section (shown in Figure 5.1 ), click the View Status History link to
view the status history of a profile.
30Payflow Recurring Payments Developer’s Guide
Getting Recurring Payments Profile Details
Obtaining Profile Details Programmatically
FIGURE 5.1 Profile Status section of Recurring Payments Profile Details page
Obtaining Profile Details Programmatically
You can obtain profile details programmatically using the Payflow SDK. Table 5.1 lists the
Payflow parameters required in the request string to obtain the details of a recurring payments
profile.The ACTION value is always I.
TABLE 5.1 Required Parameters in a Profile Status Inquiry Request
ParameterNotes
TRXTYPEThe value R for recurring payments.
TENDERThe value C for credit card or P for PayPal.
ACTIONThe value I for inquiring about recurring payments profile details.
ORIGPROFILEIDProfile ID of the profile to deactivate.
Example of Getting Recurring Payments Profile Details
The following example Payflow parameter string requests the details of a credit card recurring
payments profile.
Payflow Recurring Payments Developer’s Guide31
Getting Recurring Payments Profile Details
Example of Getting Recurring Payments Profile Details
This is the response to the request for profile details.
RESULT=0
&RESPMSG=Approved
&PROFILEID=I-26F60651P9935932P
&CORRELATIONID=d73839395ccee
&PROFILENAME=JSmith
&ACCT=510510511105105100
&START=10272008
&TERM=2
&PAYPERIOD=
&STATUS=DEACTIVATED BY MERCHANT
&PAYMENTSLEFT=2&END=
&NUMFAILPAYMENTS=0
&CURRENCY=USD
&MAXFAILPAYMENTS=4
&EMAIL=jsmith01@example.com
&DESC=TO SEE CRICKET MATCHES
&FIRSTNAME=John
&LASTNAME=Smith
&STREET=1 Main St&ZIP=95131
&CITY=San Jose
&STATE=CA
&COUNTRY=US
&FREIGHTAMT=56.00
&TAXAMT=34.00
&AUTOBILLOUTAMT=NoAutoBill
DAY
32Payflow Recurring Payments Developer’s Guide
6
Billing the Outstanding Amount
You can request to bill the outstanding amount of a profile to immediately bill the buyer for the
current past due or outstanding amount for a recurring payments profile. To bill the
outstanding amount:
z The profile status must be active or deactivated (suspended).
N OTE: You cannot activate a suspended profile in the request for billing the outstanding
amount. You must reactivate with the reactivate recurring payments profile request.
See “Deactivating and Reactivating Recurring Payments Profiles” on page 21.
z The profile must have a non-zero outstanding balance.
z The amount of the payment cannot exceed the outstanding amount for the profile.
z The request to bill the outstanding amount cannot be within 24 hours of a regularly
scheduled payment for this profile.
Log in to PayPal to determine the success or failure of the outstanding payment. See
Chapter 5, “Getting Recurring Payments Profile Details,” for information on how to obtain
profile details.
Billing the Outstanding Amount
You can bill the outstanding amount of a profile through the Payflow SDK. Table 6.1 lists the
parameters required in a request to bill the outstanding amount.The ACTION value is always P.
TABLE 6.1 Parameters Required to Retry a Transaction
ParameterNotes
TRXTYPEThe value R for recurring payments.
ACTIONThe value P for billing the outstanding amount.
ORIGPROFILEIDProfile ID of the profile for which the outstanding amount will
be billed.
Payflow Recurring Payments Developer’s Guide33
Billing the Outstanding Amount
Billing the Outstanding Amount
34Payflow Recurring Payments Developer’s Guide
7
Updating Recurring Payments
Profiles
You can update a recurring payments profile by sending a subset of the profile parameters in a
request to modify the profile.
N OTE: You can only update active or deactivated (suspended) profiles.
You can only update specific information about the profile, including the following:
z Subscriber name or address (see Updating Addresses)
z Additional billing cycles
z Billing amount, tax amount, or shipping amount (see Updating Addresses)
z Past due or outstanding amount
z Whether to bill the outstanding amount with the next billing cycle
z Maximum number of failed payments allowed
z Buyer’s credit card information (see Updating Addresses for a restriction)
z Profile description and reference
N OTE: You cannot modify the payment period (PAYPERIOD) of a profile.
N OTE: For recurring payments with Express Checkout, certain updates, such as billing
amount, are not allowed within 3 days of the scheduled billing date, and an error is
returned.
Updating Addresses
When you update the following addresses, you must enter all of address fields, not just those
that are changing:
z Subscriber shipping address
z Credit card billing address
If, for example, you want to update the street address for shipping, you must specify all of the
shipping address fields listed in Table 8.1 in Chapter 8, “Recurring Payments Reference,” not
just the SHIPTOSTREET parameter.
Updating a Profile Through Your PayPal Account
To update a profile through your PayPal account:
1. Log in to your PayPal account.
Payflow Recurring Payments Developer’s Guide35
Updating Recurring Payments Profiles
Updating a Profile Through Your PayPal Account
2. Click the Recurring Payments link either in the Tools section of the Account Overview
page or on your Profile page.
3. On the Recurring payments overview page that appears, browse for the profile.
4. In the search results, click the profile Details.
The Recurring Payments Profile Details page appears.
5. In the Profile Status section (shown in Figure 7.1 ), click Modify to update the recurring
payments profile.
The Update a recurring payments profile page appears.
FIGURE 7.1 Profile Status section of Recurring Payments Profile Details page
6. Edit the page as necessary, and click Continue or Cancel to cancel the action.
7. Review your changes on the Review a Recurring Payment profile page. Then click Submit
to update the profile or Cancel to cancel the profile changes.
8. Follow the links on the Recurring payments profile updated page to review the profile
details or to perform other profile tasks listed.
36Payflow Recurring Payments Developer’s Guide
Updating Profiles Programmatically
You can update profiles using the Payflow SDK. Table 7.1 lists the parameters you are
required to send in a request to update a profile. The ACTION value is always M.
ABLE 7.1 Parameters Required to Update Profiles
T
TRXTYPEThe value R for recurring payments.
TENDERThe value C for credit card or P for PayPal.
ACTIONThe value M for updating the profile.
ORIGPROFILEIDProfile ID of the profile to update.
Example of Updating Profiles
Updating Recurring Payments Profiles
Updating Profiles Programmatically
The following example Payflow parameter string is a request to update the shipping address
for profile ID number I-26F60651P9935932P. Updating the shipping address requires
providing values for each of the SHIPTO* parameters.
"USER=
&PWD=
&PARTNER=
SuperMerchant
SuperUserPassword
PayPal
&TRXTYPE=R
&TENDER=C
&ACTION=M
&SHIPTOFIRSTNAME=John
&SHIPTOMIDDLENAME=J
&SHIPTOLASTNAME=SMITH
&SHIPTOSTREET=1 Main St
&SHIPTOCITY=San Jose
&SHIPTOSTATE=CA
&SHIPTOCOUNTRY=US
&SHIPTOZIP=95155
&ORIGPROFILEID=I-26F60651P9935932P
&PROFILENAME=
JSmith
&EMAIL=jsmith01@example.com&
COMPANYNAME=PayPal"
The following is an example response to the request to update the profile.
TRXTYPE(Required) The transaction type R for recurring payments profile
request.
Character length and limitations: One alpha character.
ACTION(Required) The value A for creating a new recurring payments profile.
Character length and limitations: One alpha character.
TENDER(Required) The tender type. Is one of the following values:
z C = credit card
z P = PayPal
Character length and limitations: One alpha character.
TOKEN(Required when Tender is P) The TOKEN returned in the Set Express
Checkout response when the Set Express Checkout request passes the
billing type as RecurringPayments. To create a PayPal recurring
payments profile, you must pass the following:
z One L_BILLINGAGREEMENTDESCRIPTIONn string (see below)
exactly as passed in the Set Express Checkout request
-- OR --
z The BA_DESC string (see below) exactly as passed in the Set Express
Checkout request
z TENDER=P
z TOKEN returned in the Set Express Checkout response
PROFILENAME(Required) A unique name for referencing the recurring payments
profile.
Character length and limitations: 127 alphanumeric characters.
L_BILLINGAGREEMENTD
ESCRIPTIONn
(Optional) See TOKEN.. Describes the recurring payment product or
service the buyer is purchasing with a PayPal account. The string value
is exactly as it was passed in the Set Express Checkout request.
Example: ‘One-year subscription to Time magazine’
Character length and limitations: 127 alphanumeric characters.
Payflow Recurring Payments Developer’s Guide39
Recurring Payments Reference
8
Creating Recurring Payments Profiles (ACTION=A)
ABLE 8.1 Create Recurring Payments Profile Request Parameters
T
ParameterDescription
BA_DESC(Optional) See TOKEN. Describes the recurring payment product or
ACCT(Required for credit card recurring billing) Credit card number.
EXPDATE(Required for credit card recurring billing) Credit card expiration date.
AMT(Required) Amount to be billed per regular payment period, not
service the buyer is purchasing with a PayPal account. The string value
is exactly as it was passed in the Set Express Checkout request.
Example: ‘One-year subscription to Time magazine’
Character length and limitations: 127 alphanumeric characters.
Character length and limitations: 19 alphanumeric characters.
Character length and limitations: Four numeric characters in the format
MMYY.
including shipping and tax.
N OTE: All amounts in the profile creation request must be in the same
currency.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
START(Required) Beginning date for the recurring payments cycle used to
calculate when payments should be made. Use tomorrow’s date or a date
in the future.
Character length and limitations: Eight numeric characters in the format
MMDDYYYY.
TERM(Required) The total number of regular payment periods over the life of
the agreement. If there are 36 monthly payments, for example, TERM is
36.
Character length and limitations: Numeric. A value of 0 means that
payments should continue until the profile is deactivated (suspended).
40Payflow Recurring Payments Developer’s Guide
Recurring Payments Reference
Creating Recurring Payments Profiles (ACTION=A)
ABLE 8.1 Create Recurring Payments Profile Request Parameters
T
ParameterDescription
PAYPERIOD(Required) How often the regular payment occurs. On the PayPal
website, PAYPERIOD is called payment cycle. Values are:
z DAY: Every Day.
z WEEK: Weekly - Every week on the same day of the week as the first
payment.
z BIWK: Every Two Weeks - Every other week on the same day of the
week as the first payment.
z SMMO: Twice Every Month - The 1st and 15th of the month. Results
in 24 payments per year. SMMO can start on 1st to 15th of the
month, second payment 15 days later or on the last day of the month.
z FRWK: Every Four Weeks - Every 28 days from the previous
payment date beginning with the first payment date. Results in 13
payments per year.
z MONT: Monthly - Every month on the same date as the first payment.
Results in 12 payments per year.
z QTER: Quarterly - Every three months on the same date as the first
payment.
z SMYR: Twice Every Year - Every six months on the same date as the
first payment.
z YEAR: Yearly - Every 12 months on the same date as the first
payment.
8
CVV2(Optional) Card security code.
Character length and limitations: Three to four alphanumeric characters.
CURRENCY(Required) One of the following three-character currency codes:
z USD
z EUR
z GBP
z CAD
z JPY
z AUD
MAXFAILEDPAYMENTS(Optional) The number of scheduled payments for which the transaction
is allowed to fail before PayPal deactivates (suspends) a profile. The
default is 0.
For example, if you specify 3, then PayPal allows a maximum of three
failed payment periods (possibly with multiple retries during each
payment period, and possibly nonconsecutive periods). If the transaction
is not approved for any three periods (months in the example), then
PayPal deactivates the profile.
I MPORTANT: If you do not specify a value, the default value of 0
(zero) specifies no limit. Retry attempts occur until the
TERM is met.
Character length and limitations: Numeric characters.
Payflow Recurring Payments Developer’s Guide41
Recurring Payments Reference
8
Creating Recurring Payments Profiles (ACTION=A)
ABLE 8.1 Create Recurring Payments Profile Request Parameters
T
ParameterDescription
EMAIL(Optional) Buyer’s email address. This value is used when sending
DESC(Optional) Description of the goods or services being purchased.
COMPANYNAME(Optional) Company name associated with this profile.
OPTIONALTRXAMT(Optional) Initial non-recurring payment amount due immediately upon
email receipts to buyers.
Character length and limitations: 127 alphanumeric characters.
Character length and limitations: 80 alphanumeric characters.
Character length and limitations: 64 alphanumeric characters.
profile creation. Use an initial amount for enrollment or setup fees.
N OTE: All amounts in the profile creation request must be in the same
currency.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
FIRSTNAME(Optional) Bill-to first name. See NAME.
Character length and limitations: 30 alphanumeric characters.
MIDDLENAME(Optional) Bill-to middle name.
Character length and limitations: 30 alphanumeric characters.
LASTNAME(Optional) Bill-to last name.
Character length and limitations: 30 alphanumeric characters.
NAME(Optional) The subscriber’s name. When NAME is passed, do not pass
FIRSTNAME. If both NAME and FIRSTNAME are passed, either one of the
values is considered as the subscriber’s name. If FIRSTNAME only is
passed, it alone is considered the subscriber’s name.
Character length and limitations: 30 alphanumeric characters.
STREET(Optional) Bill-to street.
Character length and limitations: 150 characters.
ZIP(Optional) Bill-to postal code.
Character length and limitations: 10 characters.
CITY(Optional) Bill-to city.
Character length and limitations: 45 characters.
STATE(Optional) Bill-to state.
Character length and limitations: 45 characters.
COUNTRY(Optional) Bill-to country.
Character length and limitations: Two characters.
42Payflow Recurring Payments Developer’s Guide
Recurring Payments Reference
Creating Recurring Payments Profiles (ACTION=A)
ABLE 8.1 Create Recurring Payments Profile Request Parameters
T
ParameterDescription
PHONENUM(Optional) Telephone number.
Character length and limitations: 20 alphanumeric characters.
SHIPTOFIRSTNAME(Optional) Ship-to first name.
Character length and limitations: 30 alphanumeric characters.
SHIPTOMIDDLENAME(Optional) Ship-to middle name.
Character length and limitations: 30 alphanumeric characters.
SHIPTOLASTNAME(Optional) Ship-to last name.
Character length and limitations: 30 alphanumeric characters.
SHIPTOSTREET(Optional) Ship-to street.
Character length and limitations: 150 characters.
SHIPTOCITY(Optional) Ship-to city.
Character length and limitations: 45 characters.
8
SHIPTOSTATE(Optional) Ship-to state.
Character length and limitations: 45 characters.
SHIPTOCOUNTRY(Optional) Ship-to country.
Character length and limitations: Two characters.
SHIPTOZIP(Optional) Ship-to postal code.
Character length and limitations: 10 characters.
CARDSTART(Optional) Date that Switch or Solo card was issued.
N OTE: For a Switch or Solo transaction to be approved, either
CARDSTART or CARDISSUE must be present.
Character length and limitations: MMYY format. For example, 0308
represents March 2008.
CARDISSUE(Optional) Issue number of Switch or Solo card.
N OTE: For a Switch or Solo transaction to be approved, either
CARDSTART or CARDISSUE must be present.
Character length and limitations: Eight alphanumeric characters.
FREIGHTAMT(Optional) Total shipping amount for this order.
N OTE: You must set CURRENCY to one of the supported three-character
currency codes.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
Payflow Recurring Payments Developer’s Guide43
Recurring Payments Reference
8
Creating Recurring Payments Profiles (ACTION=A)
ABLE 8.1 Create Recurring Payments Profile Request Parameters
T
ParameterDescription
TAXAMT(Optional) Total tax amount for this order.
TRIALSTART(Optional) The billing start date of the trial payment period.
TRIALTERM(Optional) The total number of trial payment periods over the life of the
N OTE: You must set CURRENCY to one of the supported three-character
currency codes.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
N OTE: If you set any of the trial payment period parameters, you must
set all of them in the request to create a recurring payments
profile.
Character length and limitations: 8 numeric characters in the format
MMDDYYYY.
agreement. If there are 36 monthly trial payments, for example,
TRIALTERM is 36.
Character length and limitations: Numeric. A value of 0 means that
payments should continue until the profile is deactivated (suspended).
TRIALPAYPERIOD(Optional) How often the trial payment occurs. On the PayPal website,
TRIALPAYPERIOD is called payment cycle. Values are:
z DAY: Every day.
z WEEK: Weekly - Every week on the same day of the week as the first
payment.
z BIWK: Every Two Weeks - Every other week on the same day of the
week as the first payment.
z SMMO: Twice Every Month - The 1st and 15th of the month. Results
in 24 payments per year. SMMO can start on 1st to 15th of the
month, second payment 15 days later or on the last day of the month.
z FRWK: Every Four Weeks - Every 28 days from the previous
payment date beginning with the first payment date. Results in 13
payments per year.
z MONT: Monthly - Every month on the same date as the first payment.
Results in 12 payments per year.
z QTER: Quarterly - Every three months on the same date as the first
payment.
z SMYR: Twice Every Year - Every six months on the same date as the
first payment.
z YEAR: Yearly - Every 12 months on the same date as the first
payment.
44Payflow Recurring Payments Developer’s Guide
Recurring Payments Reference
Creating Recurring Payments Profiles (ACTION=A)
T
ABLE 8.1 Create Recurring Payments Profile Request Parameters
ParameterDescription
TRIALAMT(Optional) Amount of the trial payment, not including shipping and tax.
N OTE: All amounts in the profile creation request must be in the same
currency.
If you create a trial payment period, TRIALAMT is required. Otherwise it
is optional.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
TRIALFREIGHTAMT(Optional) Shipping amount for each trial payment.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
8
TRIALTAXAMT(Optional) Tax amount for each trial payment.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
FAILEDINITAMTACTION (Optional) By default, PayPal deactivates (suspends) the pending profile
in the event that the initial payment amount fails. You can override this
default behavior by setting this parameter to ContinueOnFailure,
which indicates that if the initial payment amount fails, PayPal should
add the failed payment amount to the outstanding balance for this
recurring payment profile.
When this parameter is set to ContinueOnFailure, PayPal returns a
successful recurring payments profile response and activates the
recurring payments profile for scheduled billing immediately. You
should check your PayPal account for updates to the profile’s payment
status.
If this parameter is not set or is set to CancelOnFailure, PayPal
creates the recurring payments profile but does not place it in pending
status until the initial payment is completed. If the initial payment
clears, PayPal deactivates the profile’s pending status. You should check
your account in PayPal to verify the profile status.
One of the following values:
z ContinueOnFailure
z CancelOnFailure
Payflow Recurring Payments Developer’s Guide45
Recurring Payments Reference
8
Updating Recurring Payments Profiles (ACTION=M)
ABLE 8.1 Create Recurring Payments Profile Request Parameters
T
ParameterDescription
AUTOBILLOUTSTANDING
AMT
(Optional) This parameter indicates whether or not you would like
PayPal to automatically roll over the outstanding balance amount in the
next payment.
One of the following values:
z NoAutoBill
z AddToNextBilling
T
ABLE 8.2 Create Recurring Payments Profile Response
ParameterDescription
PROFILEIDA unique identifier for future reference to the details of this recurring
payment.
Character length and limitations: 19 alphanumeric characters.
STATUSThe status of the profile. Is one of the following values:
z ACTIVE
z DEACTIVATED BY MERCHANT
z EXPIRED
z PENDING
z PROFILE TERMINATED
Updating Recurring Payments Profiles (ACTION=M)
ABLE 8.3 Update Recurring Payments Profile Request Parameters
T
ParameterDescription
TRXTYPE(Required) The transaction type R for recurring payments profile
request.
Character length and limitations: One alpha character.
TENDER(Required) The tender type. Is one of the following values:
z C = credit card
z P = PayPal
Character length and limitations: One alpha character.
ACTION(Required) The Action value M for modifying the recurring profile.
Character length and limitations: One alpha character.
ORIGPROFILEID(Required) Profile ID of the profile to reactivate.
Character length and limitations: 19 alphanumeric characters.
46Payflow Recurring Payments Developer’s Guide
Recurring Payments Reference
Updating Recurring Payments Profiles (ACTION=M)
ABLE 8.3 Update Recurring Payments Profile Request Parameters
T
ParameterDescription
NOTE(Optional) If not provided, the default string is “Modify Profile”
Character length and limitations: 256 characters.
PROFILENAME(Optional) A unique name for referencing the profile.
Character length and limitations: 128 alphanumeric characters.
ACCT(Required for credit card recurring billing) Credit card number.
Character length and limitations: 19 alphanumeric characters.
EXPDATE(Required for credit card recurring billing) Credit card expiration date.
Character length and limitations: Four numeric characters in the format
MMYY.
AMT(Required) Amount to be billed per regular payment period, not
including shipping and tax.
N OTE: All amounts in the profile creation request must be in the same
currency.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
8
START(Required) Beginning date for the recurring payments cycle used to
calculate when payments should be made. Use tomorrow’s date or a date
in the future.
Character length and limitations: 8 numeric characters in the format
MMDDYYYY.
TERM(Required) The total number of regular payment periods over the life of
the agreement. If there are 36 monthly payments, TERM is 36.
Character length and limitations: Numeric. A value of 0 means that
payments should continue until the profile is deactivated (suspended).
Payflow Recurring Payments Developer’s Guide47
Recurring Payments Reference
8
Updating Recurring Payments Profiles (ACTION=M)
T
ABLE 8.3 Update Recurring Payments Profile Request Parameters
ParameterDescription
PAYPERIOD(Required) How often the regular payment occurs. Values are:
z DAY: Every day.
z WEEK: Weekly - Every week on the same day of the week as the first
payment.
z BIWK: Every Two Weeks - Every other week on the same day of the
week as the first payment.
z SMMO: Twice Every Month - The 1st and 15th of the month. Results
in 24 payments per year. SMMO can start on 1st to 15th of the
month, second payment 15 days later or on the last day of the month.
z FRWK: Every Four Weeks - Every 28 days from the previous payment
date beginning with the first payment date. Results in 13 payments
per year.
z MONT: Monthly - Every month on the same date as the first payment.
Results in 12 payments per year.
z QTER: Quarterly - Every three months on the same date as the first
payment.
z SMYR: Twice Every Year - Every six months on the same date as the
first payment.
z YEAR: Yearly - Every 12 months on the same date as the first
payment.
ADDITIONALBILLINGCY
CLES
(Optional) Additional billing cycles as defined by PAYPERIOD to add to
this profile. If, for example, the number of billing cycles in the current
TERM is 36, setting ADDITIONALBILLINGCYCLES to 2 increases TERM
to 38.
CVV2(Optional) Card security code.
Character length and limitations: Three to four numeric characters.
CURRENCY(Required) One of the following three-character currency codes:
z USD
z EUR
z GBP
z CAD
z JPY
z AUD
48Payflow Recurring Payments Developer’s Guide
Recurring Payments Reference
Updating Recurring Payments Profiles (ACTION=M)
ABLE 8.3 Update Recurring Payments Profile Request Parameters
T
ParameterDescription
MAXFAILPAYMENTS(Optional) The number of scheduled payments for which the transaction
is allowed to fail before PayPal deactivates (suspends) a profile. The
default is 0.
For example, if you specify 3, then PayPal allows a maximum of three
failed payment periods (possibly with multiple retries during each
payment period, and possibly nonconsecutive periods). If the transaction
is not approved for any three periods (months in the example), then
PayPal deactivates the profile.
I MPORTANT: If you do not specify a value, the default value of 0
(zero) specifies no limit. Retry attempts occur until the
TERM is met.
Character length and limitations: Numeric characters.
EMAIL(Optional) Buyer’s email address. This value is used when sending email
receipts to buyers.
Character length and limitations: 127 characters.
8
DESC(Optional) Description of the goods or services being purchased.
Character length and limitations: 80 alphanumeric characters.
COMPANYNAME(Optional) Company name associated with this profile.
Character length and limitations: 64 alphanumeric characters.
OPTIONALTRXAMT(Optional) Amount to be billed per regular payment period, not
including shipping and tax.
N OTE: All amounts in the profile creation request must be in the same
currency.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
FIRSTNAME(Optional) Bill-to first name. See NAME.
Character length and limitations: 30 alphanumeric characters.
MIDDLENAME(Optional) Bill-to middle name.
Character length and limitations: 30 alphanumeric characters.
LASTNAME(Optional) Bill-to last name.
Character length and limitations: 30 alphanumeric characters.
NAME(Optional) The subscriber’s name. When NAME is passed, do not pass
FIRSTNAME. If both NAME and FIRSTNAME are passed, either one of the
values is considered as the subscriber’s name. If FIRSTNAME only is
passed, it alone is considered the subscriber’s name.
Character length and limitations: 30 alphanumeric characters.
Payflow Recurring Payments Developer’s Guide49
Recurring Payments Reference
8
Updating Recurring Payments Profiles (ACTION=M)
ABLE 8.3 Update Recurring Payments Profile Request Parameters
T
ParameterDescription
STREET(Optional) Bill-to street.
Character length and limitations: 150 characters.
ZIP(Optional) Bill-to postal code.
Character length and limitations: 10 characters.
CITY(Optional) Bill-to city.
Character length and limitations: 45 characters.
STATE(Optional) Bill-to state.
Character length and limitations: 45 characters.
COUNTRY(Optional) Bill-to country.
Character length and limitations: Two characters.
PHONENUM(Optional) Telephone number.
Character length and limitations: 20 alphanumeric characters.
SHIPTOFIRSTNAME(Optional) Ship-to first name.
Character length and limitations: 30 alphanumeric characters.
SHIPTOMIDDLENAME(Optional) Ship-to middle name.
Character length and limitations: 30 alphanumeric characters.
SHIPTOLASTNAME(Optional) Ship-to last name.
Character length and limitations: 30 alphanumeric characters.
SHIPTOSTREET(Optional) Ship-to street.
Character length and limitations: 150 characters.
SHIPTOCITY(Optional) Ship-to city.
Character length and limitations: 45 characters.
SHIPTOSTATE(Optional) Ship-to state.
Character length and limitations: 45 alphanumeric characters.
SHIPTOCOUNTRY(Optional) Ship-to country.
Character length and limitations: Two characters.
SHIPTOZIP(Optional) Ship-to postal code.
Character length and limitations: 10 characters.
CARDSTART(Optional) Date that Switch or Solo card was issued.
N OTE: For a Switch or Solo transaction to be approved, either
CARDSTART or CARDISSUE must be present.
Character length and limitations: MMYY format. For example, 0308
represents March 2008.
50Payflow Recurring Payments Developer’s Guide
Recurring Payments Reference
Updating Recurring Payments Profiles (ACTION=M)
ABLE 8.3 Update Recurring Payments Profile Request Parameters
T
ParameterDescription
CARDISSUE(Optional) Issue number of Switch or Solo card.
N OTE: For a Switch or Solo transaction to be approved, either
CARDSTART or CARDISSUE must be present.
Character length and limitations: Two alphanumeric characters.
TAXAMT(Optional) Total tax amount for this order.
N OTE: You must set CURRENCY to one of the supported three-character
currency codes.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
FAILEDINITAMTACTION (Optional) By default, PayPal deactivates (suspends) the pending profile
in the event that the initial payment amount fails. You can override this
default behavior by setting this parameter to ContinueOnFailure,
which indicates that if the initial payment amount fails, PayPal should
add the failed payment amount to the outstanding balance for this
recurring payment profile.
When this parameter is set to ContinueOnFailure, PayPal returns a
successful recurring payments profile response and activates the
recurring payments profile for scheduled billing immediately. You
should check your PayPal account for updates to the profile’s payment
status.
If this parameter is not set or is set to CancelOnFailure, PayPal
creates the recurring payments profile but does not place it in pending
status until the initial payment is completed. If the initial payment clears,
PayPal deactivates the profile’s pending status. You should check your
PayPal account to verify the profile’s status.
One of the following values:
z ContinueOnFailure
z CancelOnFailure
8
OUTSTANDINGAMT(Optional) The current past due amount for this profile.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
AUTOBILLOUTAMT(Optional) This parameter indicates whether or not you would like
PayPal to automatically bill the outstanding balance amount in the next
payment.
ABLE 8.10 View Recurring Payments Profile Details Response
T
ParameterDescription
TERMThe total number of regular payment periods over the life of the
agreement. If there are 36 monthly payments, TERM is 36.
Character length and limitations: Numeric. A value of 0 means that
payments should continue until the profile is deactivated (suspended).
PAYPERIODHow often the payment occurs. On the PayPal website, PAYPERIOD is
called payment cycle. Values are:
z DAY: Every day.
z WEEK: Weekly - Every week on the same day of the week as the first
payment.
z BIWK: Every Two Weeks - Every other week on the same day of the
week as the first payment.
z SMMO: Twice Every Month - The 1st and 15th of the month. Results
in 24 payments per year. SMMO can start on 1st to 15th of the
month, second payment 15 days later or on the last day of the
month.
z FRWK: Every Four Weeks - Every 28 days from the previous
payment date beginning with the first payment date. Results in 13
payments per year.
z MONT: Monthly - Every month on the same date as the first payment.
Results in 12 payments per year.
z QTER: Quarterly - Every three months on the same date as the first
payment.
z YEAR: Yearly - Every 12 months on the same date as the first
payment.
z SMYR: Twice Every Year - Every six months on the same date as the
first payment.
8
NUMCYCLESCOMPLETEDThe number of billing cycles, as defined by PAYPERIOD, completed in
the current active TERM. A billing cycle is considered complete only
after retry attempts to collect payment for the current billing cycle have
failed.
Character length and limitations: Numeric.
STATUSOne of the following values describing the current status of the profile:
z ACTIVE
z PROFILE TERMINATED
z DEACTIVATED BY MERCHANT
z EXPIRED
z PENDING
PAYMENTSLEFTNumber of payments left to be billed.
Character length and limitations: Numeric characters.
NEXTPAYMENTDate that the next payment is due.
Character length and limitations: MMDDYYYY format.
ABLE 8.10 View Recurring Payments Profile Details Response
T
ParameterDescription
CVV2MATCHOne of the following card security code match responses:
z Y = Match
z N = No match
z X = Unknown
NUMFAILPAYMENTSNumber of payments that failed.
Character length and limitations: Numeric characters.
CURRENCYOne of the following three-character currency codes:
z USD
z EUR
z GBP
z CAD
z JPY
z AUD
MAXFAILPAYMENTSThe number of scheduled payments for which the transaction is allowed
to fail before PayPal deactivates (suspends) a profile. The default is 0.
I MPORTANT: If you do not specify a value, the default value of 0
(zero) specifies no limit. Retry attempts occur until the
TERM is met.
Character length and limitations: Numeric characters.
EMAILBuyer’s email address.
Character length and limitations: 127 characters.
DESCDescription of the goods or services being purchased.
Character length and limitations: 80 alphanumeric characters.
COMPANYNAMECompany name associated with this profile.
Character length and limitations: 64 alphanumeric characters.
OPTIONALTRXAMTInitial non-recurring payment amount due immediately upon profile
creation. Use an initial amount for enrollment or setup fees.
N OTE: All amounts in the profile creation request must be in the same
currency.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
FIRSTNAMEBill-to first name.
Character length and limitations: 30 alphanumeric characters.
MIDDLENAMEBill-to middle name.
Character length and limitations: 30 alphanumeric characters.
ABLE 8.10 View Recurring Payments Profile Details Response
T
ParameterDescription
CARDSTARTDate that Switch or Solo card was issued.
N OTE: For a Switch or Solo transaction to be approved, either
Character length and limitations: MMYY format. For example, 0308
represents March 2008.
CARDISSUEIssue number of Switch or Solo card.
N OTE: For a Switch or Solo transaction to be approved, either
Character length and limitations: Eight alphanumeric characters.
FREIGHTAMTTotal shipping amount for this order.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
CARDSTART or CARDISSUE must be present.
CARDSTART or CARDISSUE must be present.
TAXAMTTotal tax amount for this order.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
TRIALSTARTThe billing start date of the trial payment period.
N OTE: If you set any of the trial payment period parameters, you must
set all of them in the request to create a recurring payments
profile.
Character length and limitations: 8 numeric characters in the format
MMDDYYYY.
TRIALTERMThe total number of trial payment periods over the life of the
agreement. If there are 36 monthly trial payments, for example,
TRIALTERM is 36.
Character length and limitations: Numeric. A value of 0 means that
payments should continue until the profile is deactivated (suspended).
ABLE 8.10 View Recurring Payments Profile Details Response
T
ParameterDescription
TRIALPAYPERIODHow often the trial payment occurs. On the PayPal website,
TRIALPAYPERIOD is called payment cycle. Values are:
z DAY: Every day.
z WEEK: Weekly - Every week on the same day of the week as the first
payment.
z BIWK: Every Two Weeks - Every other week on the same day of the
week as the first payment.
z SMMO: Twice Every Month - The 1st and 15th of the month. Results
in 24 payments per year. SMMO can start on 1st to 15th of the
month, second payment 15 days later or on the last day of the
month.
z FRWK: Every Four Weeks - Every 28 days from the previous
payment date beginning with the first payment date. Results in 13
payments per year.
z MONT: Monthly - Every month on the same date as the first payment.
Results in 12 payments per year.
z QTER: Quarterly - Every three months on the same date as the first
payment.
z YEAR: Yearly - Every 12 months on the same date as the first
payment.
z SMYR: Twice Every Year - Every six months on the same date as the
first payment.
8
TRIALAMTAmount of the trial payment, not including shipping and tax.
N OTE: All amounts in the profile creation request must be in the same
currency.
If you create a trial payment period, TRIALAMT is required. Otherwise it
is optional.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
TRIALFREIGHTAMTShipping amount for each trial payment.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
TRIALTAXAMTTax amount for each trial payment.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
ABLE 8.10 View Recurring Payments Profile Details Response
ParameterDescription
FAILEDINITAMTACTIONBy default, PayPal deactivates (suspends) the pending profile in the
event that the initial payment amount fails. You can override this default
behavior by setting this parameter to ContinueOnFailure, which
indicates that if the initial payment amount fails, PayPal should add the
failed payment amount to the outstanding balance for this recurring
payment profile.
When this parameter is set to ContinueOnFailure, PayPal returns a
successful recurring payments profile response and activates the
recurring payments profile for scheduled billing immediately. You
should check your PayPal account for updates to the profile’s payment
status.
If this parameter is not set or is set to CancelOnFailure, PayPal
creates the recurring payments profile but does not place it in pending
status until the initial payment is completed. If the initial payment
clears, PayPal cancels the profile’s pending status. You should check
your PayPal account to verify the profile’s status.
One of the following values:
z ContinueOnFailure
z CancelOnFailure
OUTSTANDINGAMTThe current past due amount for this profile.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
LASTPAYMENTAMTAmount of the last successful payment received for this profile.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
AUTOBILLOUTAMTThis parameter indicates whether or not you would like PayPal to
automatically roll over the outstanding balance amount in the next
payment.
One of the following values:
z NoAutoBill
z AddToNextBilling
60Payflow Recurring Payments Developer’s Guide
Recurring Payments Reference
Billing Outstanding Amount Request (ACTION=P)
Billing Outstanding Amount Request (ACTION=P)
TABLE 8.11 Bill Outstanding Amount Request Parameters
ParameterDescription
TRXTYPE(Required) The transaction type R for recurring payments profile
request.
Character length and limitations: One alpha character.
ACTION(Required) The Action value P for billing outstanding amount.
Character length and limitations: One alpha character.
ORIGPROFILEID(Required) Profile ID of the profile to bill outstanding amount.
Character length and limitations: 19 alphanumeric characters.
AMT(Optional) Amount to be billed per regular payment period, not
including shipping and tax.
8
N OTE: All amounts in the profile creation request must be in the same
currency.
Limitations: Nine numeric characers plus decimal (.) character. No
currency symbol. Specify the exact amount to the cent using a decimal
point—use 34.00, not 34. Do not include comma separators—use
1199.95 not 1,199.95.
CURRENCY(Optional) One of the following three-character currency codes:
z USD
z EUR
z GBP
z CAD
z JPY
z AUD
NOTE(Optional) Notes about the action. If not provided, the following default
string is sent:
“This is a recurring payment”
Character length and limitations: 256 characters.
ABLE 8.12 Bill Outstanding Amount Response
T
ParameterDescription
PROFILEIDA unique identifier for future reference to the details of this recurring
payment.
Character length and limitations: 19 alphanumeric characters.