Website Payments Pro Payflow Edition Recurring Payments Developer’s Guide Last updated: January 2010
Website Payments Pro Payflow Edition - Recurring Payments Developer’s Guide Document Number: 200040.en_US-201001 © 2010 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Where To Go For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Chapter 1 Recurring Payments Overview . . . . . . . . . . . . . . . 7 About the Payflow Recurring Payment Services. . . . . . .
Contents Example of Reactivating a Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Chapter 4 Canceling Recurring Payments Profiles . . . . . . . . . . . 25 Canceling Recurring Payments Profiles Through Your PayPal Account. . . . . . . . . . . 25 Chapter 5 Getting Recurring Payments Profile Details . . . . . . . . . 29 Profile Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Obtaining Profile Details Through Your PayPal Account . . . .
Preface 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.
Revision History TABLE 1.1 Revision history 6 Date Changes August 2009 Added an example of obtaining a TOKEN from the Set Express Checkout response to create a Recurring Payments profile for billing a PayPal account.
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 z z A buyer purchases a subscription to a magazine or newsletter from your site and agrees to pay a monthly fee. 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.
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.
Recurring Payments Overview Limitations Limitations The current release of Payflow recurring payments has the following limitations: z z A recurring payments profile can have at most one optional trial payment period and a single regular payment period. 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.
Recurring Payments Overview Recurring Payments Terms 10 Payflow Recurring Payments Developer’s Guide
2 Creating Recurring Payments Profiles N O T E : 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.
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.
Creating Recurring Payments Profiles Creating Recurring Payments Profiles Programmatically FIGURE 2.2 Profile created Creating Recurring Payments Profiles Programmatically You can create recurring payments profiles programmatically using the Payflow SDK. Table 2.1 lists the Payflow parameters required in the request string to create a new profile. The ACTION value for creating a profile is always A. TABLE 2.
Creating Recurring Payments Profiles Options for Creating a Recurring Payments Profile Programmatically TABLE 2.1 Required Parameters to Create a New Profile Parameter Notes ACTION The value A for creating a new recurring payments profile. PROFILENAME Unique profile name. ACCT Credit card account number. Required for credit card billing only. EXPDATE Credit card expiration date. Required for credit card billing only. AMT The amount to bill. START Start date for the recurring payment.
Creating Recurring Payments Profiles 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.
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.
Creating Recurring Payments Profiles Example: Creating a Recurring Payments Profile For Billing a Credit Card Create Credit Card Recurring Payments Profile Request "USER=SuperMerchant &PWD=SuperUserPassword &PARTNER=PayPal &TRXTYPE=R &TENDER=C &ACTION=A &PROFILENAME=J Smith &ACCT=510510511105105100 &EXPDATE=1209 &CVV2=657 &AMT=60.00 &START=10272009 &TERM=10 &PAYPERIOD=MONT &CURRENCY=USD &MAXFAILPAYMENTS=4 &EMAIL=jsmith01@example.com &COMPANYNAME=PayPal &DESC=To See Cricket Matches &OPTIONALTRXAMT=10.
Creating Recurring Payments Profiles 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 typ
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.
Creating Recurring Payments Profiles Example: Creating a Recurring Payments Profile For Billing a PayPal Account 20 Payflow Recurring Payments Developer’s Guide
3 Deactivating and Reactivating 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 O T E : 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 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.
Deactivating and Reactivating Recurring Payments Profiles Deactivating a Profile Programmatically 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.
Deactivating and Reactivating Recurring Payments Profiles Example of Reactivating a Profile "USER=SuperMerchant &PWD=SuperUserPassword &PARTNER=PayPal &TRXTYPE=R &TENDER=C &ACTION=C &ORIGPROFILEID=I-26F60651P9935932P" This is the example response. RESULT=0 &RESPMSG=Approved &RPREF=RRRF0A08BD4D &PROFILEID=I-26F60651P9935932P &CORRELATIONID=f87c07be9f95 Example of Reactivating a Profile The following example request reactivates a profile.
4 Canceling 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 O T E : 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.
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.
Canceling Recurring Payments Profiles Canceling Recurring Payments Profiles Through Your PayPal Account FIGURE 4.
Canceling Recurring Payments Profiles Canceling Recurring Payments Profiles Through Your PayPal Account 28 Payflow Recurring Payments Developer’s Guide
5 Getting Recurring Payments Profile Details You can request to get details of a profile.
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.
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.
Getting Recurring Payments Profile Details Example of Getting Recurring Payments Profile Details "USER=SuperMerchant &PWD=SuperUserPassword &PARTNER=PayPal &TRXTYPE=R &TENDER=C &ACTION=I &ORIGPROFILEID=I-26F60651P9935932P" This is the response to the request for profile details.
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 O T E : You cannot activate a suspended profile in the request for billing the outstanding amount. You must reactivate with the reactivate recurring payments profile request.
Billing the Outstanding Amount Billing the Outstanding Amount 34 Payflow 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 O T E : You can only update active or deactivated (suspended) profiles.
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.
Updating Recurring Payments Profiles Updating Profiles Programmatically 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. TABLE 7.1 Parameters Required to Update Profiles TRXTYPE The value R for recurring payments. TENDER The value C for credit card or P for PayPal. ACTION The value M for updating the profile.
Updating Recurring Payments Profiles Example of Updating Profiles 38 Payflow Recurring Payments Developer’s Guide
8 Recurring Payments Reference Creating Recurring Payments Profiles (ACTION=A) TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description 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.
8 Recurring Payments Reference Creating Recurring Payments Profiles (ACTION=A) TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description BA_DESC (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.
Recurring Payments Reference Creating Recurring Payments Profiles (ACTION=A) 8 TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description 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.
8 Recurring Payments Reference Creating Recurring Payments Profiles (ACTION=A) TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description EMAIL (Optional) Buyer’s email address. This value is used when sending email receipts to buyers. Character length and limitations: 127 alphanumeric characters. DESC (Optional) Description of the goods or services being purchased. Character length and limitations: 80 alphanumeric characters.
Recurring Payments Reference Creating Recurring Payments Profiles (ACTION=A) 8 TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description 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.
8 Recurring Payments Reference Creating Recurring Payments Profiles (ACTION=A) TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description TAXAMT (Optional) Total tax amount for this order. N O T E : 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.
Recurring Payments Reference Creating Recurring Payments Profiles (ACTION=A) 8 TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description TRIALAMT (Optional) Amount of the trial payment, not including shipping and tax. N O T E : 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.
8 Recurring Payments Reference Updating Recurring Payments Profiles (ACTION=M) TABLE 8.1 Create Recurring Payments Profile Request Parameters Parameter Description AUTOBILLOUTSTANDING (Optional) This parameter indicates whether or not you would like AMT PayPal to automatically roll over the outstanding balance amount in the next payment. One of the following values: z NoAutoBill z AddToNextBilling TABLE 8.
Recurring Payments Reference Updating Recurring Payments Profiles (ACTION=M) 8 TABLE 8.3 Update Recurring Payments Profile Request Parameters Parameter Description 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.
8 Recurring Payments Reference Updating Recurring Payments Profiles (ACTION=M) TABLE 8.3 Update Recurring Payments Profile Request Parameters Parameter Description 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.
Recurring Payments Reference Updating Recurring Payments Profiles (ACTION=M) 8 TABLE 8.3 Update Recurring Payments Profile Request Parameters Parameter Description 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.
8 Recurring Payments Reference Updating Recurring Payments Profiles (ACTION=M) TABLE 8.3 Update Recurring Payments Profile Request Parameters Parameter Description 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.
Recurring Payments Reference Updating Recurring Payments Profiles (ACTION=M) 8 TABLE 8.3 Update Recurring Payments Profile Request Parameters Parameter Description CARDISSUE (Optional) Issue number of Switch or Solo card. N O T E : 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.
8 Recurring Payments Reference Deactivating Recurring Payments Profiles (ACTION=C) TABLE 8.4 Update Recurring Payments Profile Response Parameter Description PROFILEID A unique identifier for future reference to the details of this recurring payment. Character length and limitations: 19 alphanumeric characters. Deactivating Recurring Payments Profiles (ACTION=C) TABLE 8.
Recurring Payments Reference Reactivating Recurring Payments Profiles (ACTION=R) 8 Reactivating Recurring Payments Profiles (ACTION=R) TABLE 8.7 Reactivate Recurring Payments Profile Request Parameters Parameter Description TRXTYPE (Required) The transaction type R for recurring payments profile request. Character length and limitations: One alpha character. TENDER (Required) The tender type.
8 Recurring Payments Reference Viewing Recurring Payments Profile Details (ACTION=I) TABLE 8.9 View Recurring Payments Profile Details Request Parameters Parameter Description 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 I for viewing recurring payments profile. Character length and limitations: One alpha character.
Recurring Payments Reference Viewing Recurring Payments Profile Details (ACTION=I) 8 TABLE 8.10 View Recurring Payments Profile Details Response Parameter Description TERM 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). PAYPERIOD How often the payment occurs.
8 Recurring Payments Reference Viewing Recurring Payments Profile Details (ACTION=I) TABLE 8.10 View Recurring Payments Profile Details Response Parameter Description CVV2MATCH One of the following card security code match responses: z Y = Match z N = No match z X = Unknown NUMFAILPAYMENTS Number of payments that failed. Character length and limitations: Numeric characters.
Recurring Payments Reference Viewing Recurring Payments Profile Details (ACTION=I) 8 TABLE 8.10 View Recurring Payments Profile Details Response Parameter Description LASTNAME Bill-to last name. Character length and limitations: 30 alphanumeric characters. NAME Subscriber’s name. Character length and limitations: 30 alphanumeric characters. STREET Bill-to street. Character length and limitations: 150 characters. ZIP Bill-to postal code. Character length and limitations: 10 characters.
8 Recurring Payments Reference Viewing Recurring Payments Profile Details (ACTION=I) TABLE 8.10 View Recurring Payments Profile Details Response Parameter Description CARDSTART Date that Switch or Solo card was issued. N O T E : 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 Issue number of Switch or Solo card.
Recurring Payments Reference Viewing Recurring Payments Profile Details (ACTION=I) 8 TABLE 8.10 View Recurring Payments Profile Details Response Parameter Description TRIALPAYPERIOD 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.
8 Recurring Payments Reference Viewing Recurring Payments Profile Details (ACTION=I) TABLE 8.10 View Recurring Payments Profile Details Response 60 Parameter Description FAILEDINITAMTACTION By default, PayPal deactivates (suspends) the pending profile in the event that the initial payment amount fails.
Recurring Payments Reference Billing Outstanding Amount Request (ACTION=P) 8 Billing Outstanding Amount Request (ACTION=P) TABLE 8.11 Bill Outstanding Amount Request Parameters Parameter Description 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.
8 62 Recurring Payments Reference Billing Outstanding Amount Request (ACTION=P) Payflow Recurring Payments Developer’s Guide
Index A D ACCT 14, 40, 47, 54 ACTION 39, 46, 52, 53, 54, 61 ACTION=A 14 ACTION=C 23, 31, 33, 37 ACTIVE 29 ADDITIONALBILLINGCYCLES 48 AMT 14, 15, 40, 47, 54, 61 AUTOBILLOUTAMT 51, 60 AUTOBILLOUTSTANDINGAMT 46 DEACTIVATED BY MERCHANT 29 deactivating profiles parameters required 23 deactivating recurring payments profiles 21 DESC 42, 49, 56 B BA_DESC 14, 40 billilng credit cards 16 billing outstanding amount 16 required parameters 33 requirements 33 billing PayPal accounts 19 billing the outstanding amount
Index MAXFAILPAYMENTS 49, 56 MIDDLENAME 42, 49, 56 regular payment period 9 defined 9 N S NAME 42, 49, 57 NEXTPAYMENT 55 NOTE 47, 52, 53, 61 NUMCYCLESCOMPLETED 55 NUMFAILPAYMENTS 56 setting number of failed scheduled payments 16 SHIPTOCITY 43, 50, 57 SHIPTOCOUNTRY 43, 50, 57 SHIPTOFIRSTNAME 43, 50, 57 SHIPTOLASTNAME 43, 50, 57 SHIPTOMIDDLENAME 43, 50, 57 SHIPTOSTATE 43, 50, 57 SHIPTOSTREET 43, 50, 57 SHIPTOZIP 43, 50, 57 specifying a regular payment period 15 specifying an initial payment 15 specifyin
Index U updating recurring payments profiles 46 information that can be updated 35 required parameters 35 updating addresses 35 updating shipping address in profiles 37 V viewing recurring payments profiles 53 Z ZIP 42, 50, 57 Payflow Recurring Payments Developer’s Guide 65
Index 66 Payflow Recurring Payments Developer’s Guide
