Payflow Pro Recurring Billing Service User’s Guide Last updated: December 2012
Payflow Pro – Recurring Billing Service User’s Guide Document Number: 200012.en_US-201212 © 2012 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. PayPal (Europe) S.à r.l.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Organization of This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Using the Cancel Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Example Cancel Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Example Response to the Cancel Action . . . . . . . . . . . . . . . . . . . . . . . . 27 Required Parameters for the Cancel Action . . . . . . . . . . . . . . . . . . . . . . . . . 27 Returned Values for the Cancel Action . . . . . . . . . . . . . . . . . . . . . . . . .
Preface This Guide This guide describes how to use the Payflow SDK to perform recurring billing transactions. The Recurring Billing Service is a scheduled payment solution that enables you to automatically bill your customers at regular intervals – for example, a monthly fee of $42 for 36 months with an initial fee of $129.
Preface Where To Go For More Information Appendix A, “Obtaining Consent to Bill Customers Using Recurring Billing,” outlines your responsibilities in obtaining prior authorization from the customer to bill on an automated schedule. Where To Go For More Information For more information, see the following: Payflow Pro Developer’s Guide Describes Payflow Pro, a high performance TCP/IP-based Internet payment gateway solution.
Preface Revision History Revision History TABLE P.1 Revision History Date Description December 2012 Updated description of RETRYNUMDAYS parameter. January 2010 Added using Inquiry to view recurring transaction and optional transaction details in a profile. Included example. October 2009 Added support for optional transactions that are used to validate the buyer’s account information. No amount is passed with this option.
Preface Revision History 8 December 2012 Payflow Pro Recurring Billing Service User’s Guide
1 Managing Payflow Services This chapter provides a high-level overview of the tasks you can perform using PayPal Manager and the Payflow SDK. IMPO RTANT: You must have prior authorization from the customer to bill on an automated schedule. See Appendix A, “Obtaining Consent to Bill Customers Using Recurring Billing,” for additional details.
1 Managing Payflow Services Recurring Billing Terms Recurring Billing Terms Table 1.1 describes terms you should be familiar with when using the Recurring Billing Service. TABLE 1.1 Recurring billing terms Term Meaning Payment Sum that is transacted during each payment period. Payments differ from transactions. Several transactions may be required to successfully perform a payment for a payment period; for example, due to a lack of funds during the first transaction attempts.
Managing Payflow Services Overview of the Payflow Services Interface in PayPal Manager 1 Modify (ACTION=M) Modify any setting in the profile. You have the option to run an Optional Transaction. Reactivate (ACTION=R) Reactivate the specified inactive profile. You specify a new start date and have the option to alter any other profile parameter. Cancel (ACTION=C) Deactivate the recurring profile. PayPal records the cancellation date.
1 12 Managing Payflow Services Overview of the Payflow Services Interface in PayPal Manager December 2012 Payflow Pro Recurring Billing Service User’s Guide
2 Using the SDK to Perform Recurring Tasks N OTE : You should be familiar with the Payflow SDK to use the information presented in this chapter. See Payflow Pro Developer’s Guide for full documentation of the SDK. The Payflow SDK operations described in this chapter are available only to merchants with the Payflow services. This chapter describes the use of the Payflow SDK to perform recurring transactions.
2 Using the SDK to Perform Recurring Tasks Using the Add Action TABLE 2.1 Action value definitions ACTION Value Description Modify M Make changes to an existing profile. If the profile is currently inactive, then the Modify action reactivates it. See “Using the Modify and Reactivate Actions” on page 21. Reactivate R Reactivate an inactive profile. See “Using the Modify and Reactivate Actions” on page 21. Cancel C Deactivate an existing profile. See “Using the Cancel Action” on page 26.
Using the SDK to Perform Recurring Tasks Using the Add Action 2 An Authorization transaction to validate the customer’s account information before creating the profile. No amount is passed with this option. (This transaction option is also known as zero-dollar authorization.) The recurring profile record keeps track of the total amount collected as a result of optional Sale transactions in addition to the normal recurring transactions.
2 Using the SDK to Perform Recurring Tasks Required Parameters for the Add Action "TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4&ACTIO N=A&PROFILENAME=RegularSubscription&AMT=42.00&ACCT=4012888888881881&EXPDATE =0203&START=12012008&PAYPERIOD=WEEK&TERM=12&OPTIONALTRX=S&OPTIONALTRXAMT=2. 00&COMMENT1=First-time customer" Adding a New Profile for a PayPal Account The following example Payflow parameter string creates a recurring billing profile that bills a PayPal account.
Using the SDK to Perform Recurring Tasks Required Parameters for the Add Action TABLE 2.2 2 Required recurring profile parameters for the Add action(Continued) Parameter Description Usage (Length) ACTION Specifies Add, Modify, Cancel, Reactivate, Inquiry, or Payment. Must be “A” (1) PROFILENAME Name for the profile (user-specified). Can be used to search for a profile. Non-unique identifying text name Alphanumeric(128) ACCT Required when TENDER=C or TENDER=A.
2 Using the SDK to Perform Recurring Tasks Required Parameters for the Add Action TABLE 2.2 18 Required recurring profile parameters for the Add action(Continued) Parameter Description Usage (Length) PAYPERIOD Specifies how often the payment occurs: WEEK: Weekly - Every week on the same day of the week as the first payment. BIWK: Every Two Weeks - Every other week on the same day of the week as the first payment. SMMO: Twice Every Month - The 1st and 15th of the month.
Using the SDK to Perform Recurring Tasks Required Parameters for the Add Action 2 Optional Parameters for the Add Action TABLE 2.3 Optional recurring profile parameters for Add action Parameter Description Usage (Length) ORIGID PNREF value (length=12) of the original transaction used to create a new profile. Alphaumeric (19) N O T E : ORIGID is optional when TENDER=C or TENDER=A.
2 Using the SDK to Perform Recurring Tasks Required Parameters for the Add Action TABLE 2.3 Optional recurring profile parameters for Add action (Continued) Parameter Description Usage (Length) OPTIONALTRXAMT Amount of the Optional Transaction. Required only when OPTIONALTRX=S. N O T E : Do not specify an amount when OPTIONALTRX=A. The amount will be ignored. STREET Billing street. Alphanumeric (150) ZIP Billing postal code.
Using the SDK to Perform Recurring Tasks Using the Modify and Reactivate Actions 2 Using the Modify and Reactivate Actions You can Modify (ACTION=M) any profile value by sending any subset of the profile parameters. If the profile is currently inactive (because you deactivated it), then the Modify action reactivates it. N OTE : The Modify action cannot reactivate a profile that PayPal canceled.
2 Using the SDK to Perform Recurring Tasks Required Parameters for the Modify and Reactivate Actions Example Response to a Modify or Reactivate Action The following is an example response to a Modify or Reactivate action. Returned values are described in “Returned Values for the Modify or Reactivate Actions” on page 26.
Using the SDK to Perform Recurring Tasks Required Parameters for the Modify and Reactivate Actions TABLE 2.7 2 Optional recurring profile fields for Modify and Reactivate Parameter Description ORIGPROFILEID Required for Modify action. Profile ID of the profile that gets the action. Profile IDs for test profiles start with RT. Profile IDs for live profiles start with RP. AMT Dollar amount to be billed. Can be used to search for a profile.
2 Using the SDK to Perform Recurring Tasks Required Parameters for the Modify and Reactivate Actions TABLE 2.7 24 Optional recurring profile fields for Modify and Reactivate Parameter Description Usage (Length) PAYPERIOD Specifies how often the payment occurs. Note: For ACTION=Modify, if START is not specified, then the next payment is calculated based on last payment date. All PAYPERIOD values must use capital letters, as shown here.
Using the SDK to Perform Recurring Tasks Required Parameters for the Modify and Reactivate Actions TABLE 2.7 2 Optional recurring profile fields for Modify and Reactivate Parameter Description Usage (Length) EMAIL Customer email address. This value is used when sending email receipts to customers. The presence of email address is the indicator that an email should be sent. IMPORTANT: You must specify additional text for the message using PayPal Manager. For details, see PayPal Manager online help.
2 Using the SDK to Perform Recurring Tasks Using the Cancel Action Returned Values for the Modify or Reactivate Actions TABLE 2.8 Response values for Modify and Reactivate actions Field Description RESULT Result value for the action. PROFILEID The Profile ID of the original profile. Profile IDs for test profiles start with the characters RT. Profile IDs for live profiles start with RP. RESPMSG Optional response message. RPREF Reference number to this particular action request.
Using the SDK to Perform Recurring Tasks Required Parameters for the Cancel Action 2 Example Response to the Cancel Action Returned values are described in “Returned Values for the Cancel Action” on page 27. RESULT=0&RPREF=RWY504915344&PROFILEID=RP000000001234&RESPMSG=Approved&TRXRE SULT=0&TRXPNREF=VWYA04915345&TRXRESPMSG=Approved&AUTHCODE=489PNI Required Parameters for the Cancel Action TABLE 2.
2 Using the SDK to Perform Recurring Tasks Using the Inquiry Action to View the Status of the Profile – To view the optional transaction details, pass the PAYMENTHISTORY=O name-value pair with the Inquiry action. To view the status of a customer’s profile, submit an Inquiry action that does not include the PAYMENTHISTORY parameter (alternatively, submit PAYMENTHISTORY=N, the default value). This use is described in this section.
Using the SDK to Perform Recurring Tasks Using the Inquiry Action to View the Status of the Profile 2 Required Parameters for the Profile Status Inquiry Action TABLE 2.12 Required parameters for the Inquiry action Parameter Description Usage (Length) TRXTYPE Specifies a recurring profile request. Must be “R” (1) ACTION Specifies action to take. Must be “I” (1) ORIGPROFILEID Profile ID of the profile to inquire about. Profile IDs for test profiles start with RT.
2 Using the SDK to Perform Recurring Tasks Using the Inquiry Action to View the Status of the Profile TABLE 2.13 Response fields for Inquiry actions (Continued) Field Description TENDER Tender Type. PAYMENTSLEFT Number of payments left to be billed. N O T E : This value decreases by 1 after each payment period, regardless whether the payment failed or succeeded. To ensure that you receive funds for each payment period, you must monitor payments and follow up on any failed payments.
Using the SDK to Perform Recurring Tasks Using the Inquiry Action to View the Status of Payments 2 TABLE 2.13 Response fields for Inquiry actions (Continued) Field Description SHIPTOLASTNAME Last name of the ship-to person. SHIPTOSTREET Shipping street. SHIPTOCITY Shipping city. SHIPTOSTATE Shipping state. SHIPTOZIP Shipping postal code. SHIPTOCOUNTRY Shipping country.
2 Using the SDK to Perform Recurring Tasks Using the Inquiry Action to View the Status of Payments RESULT=0&RPREF=RKM500141021&PROFILEID=RT0000000100&P_PNREF1=VWYA06156256&P_ TRANSTIME1=21-May-04 04:47 PM&P_RESULT1=0&P_TENDER1=C&P_AMT1=1.00&P_TRANSTATE1=8&P_PNREF2=VWYA06156269 &P_TRANSTIME2=27-May-04 01:19 PM&P_RESULT2=0&P_TENDER2=C&P_AMT2=1.00&P_TRANSTATE2=8&P_PNREF3=VWYA06157650 &P_TRANSTIME3=03-Jun-04 04:47 PM&P_RESULT3=0&P_TENDER3=C&P_AMT3=1.
Using the SDK to Perform Recurring Tasks Required Parameters for the Status of Payments Inquiry Action 2 Required Parameters for the Status of Payments Inquiry Action TABLE 2.14 Required parameters for the Inquiry action Parameter Description Usage (Length) PAYMENTHISTORY Recurring transaction details are returned when the value is Y. Optional transaction details, if any, are returned when the value is O. Must be Y or O (1) TRXTYPE Specifies a recurring profile request.
2 Using the SDK to Perform Recurring Tasks Using the Payment Action TABLE 2.15 Return parameters for a Status of Payments Inquiry Action(Continued) Field Description P_TRANSTIMEn The timestamp for the transaction in the dd-mmm-yy hh:mm AM/PM format, for example, 17-Jun-04 04:47 PM. P_AMTn Amount in US dollars that was billed. Using the Payment Action The Payment action (ACTION=P) performs a real-time retry on a transaction that is in the retry state.
Using the SDK to Perform Recurring Tasks Required Parameters for the Payment Action 2 Required Parameters for the Payment Action TABLE 2.16 Parameters for the Payment action Parameter Description Usage (Length) TRXTYPE Specifies a recurring profile request. Must be “R” (1) ACTION Specifies action to take. Must be “P” (1) ORIGPROFILEID Profile ID of the profile of the transaction to retry. Profile IDs for test profiles start with RT. Profile IDs for live profiles start with RP.
2 Using the SDK to Perform Recurring Tasks Required Parameters for the Payment Action Returned Values if You Specify an Optional Transaction Table 2.18 lists values that are included in the response if the transaction involved is an Optional transaction. Other payment-related fields could also be returned, depending on your configuration (for example, verbosity level). TABLE 2.
3 Testing Recurring Billing This chapter provides the information you need to test recurring billing. In This Chapter “Testing Guidelines” on page 37 “Credit Card Numbers Used for Testing” on page 37 “Testing Result Value Responses” on page 38 Testing Guidelines PayPal provides test card numbers. Other numbers produce an error. Expiration Date must be a valid date in the future (use the mm/yy format).
3 Testing Recurring Billing Testing Result Value Responses TABLE 3.1 Test credit card numbers Visa 4012888888881881 Visa 4222222222222 N OTE : Even though this number has a different character count than the other test numbers, it is the correct and functional number. Testing Result Value Responses You can use the amount of the transaction to generate a particular result value. This table lists the general guidelines for specifying amounts. TABLE 3.
Obtaining Consent to Bill Customers Using Recurring Billing A You must obtain each customer’s consent to bill them on an automated schedule. Here is the relevant section from PayPal’s Merchant Services Agreement: Merchant shall be solely responsible for: Obtaining all necessary approvals required from each customer authorizing Merchant to bill such customer’s credit card account.
A 40 Obtaining Consent to Bill Customers Using Recurring Billing December 2012 Payflow Pro Recurring Billing Service User’s Guide
A M account verification 19, 25 ACCT 17, 22 ACTION 17, 22 actions Add 14 Cancel 26 Inquiry 14 Modify 21 overview 13 Payment 34 Reactivate 21 Add action defined 14 required parameters 16 response strings 20 adding profiles 14 AMT 17, 23 MAXFAILPAYMENTS 19, 24 Modify action defined 21 parameters 22 response strings 26 modifying profiles 21 B BAID 17 C Cancel action defined 26 required parameters 27 response strings 27 cancelling profiles 26 COMPANYNAME 19, 25 credit card account validation 15 CURRENCY 22
Add action 20 Cancel action 27 Modify action 26 Payment action 35 Reactivate action 26 retrying transactions 34 RPREF 20 S START 17, 23 status inquiring profile 14 STREET 20, 25 T TENDER 16 TERM 17, 23 Term defined 10 transactions retrying 34 TRXTYPE 16, 22 V validating accounts 15 Z zero-dollar authorization 15 ZIP 20, 25 42 Recurring Billing Service User’s Guide
