PayPal Payflow Pro - 2011 User's Guide
Payflow Pro
Recurring Billing
Service User’s Guide
Last updated: July 2011
Payflow Pro – Recurring Billing Servic e U se r’ s Gu id e
Document Number: 200012.en_US-201203
© 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. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard
Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349.
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained 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 f rom 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.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Organization of This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Where To Go For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
How to Contact Customer Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1 Managing Payflow Services . . . . . . . . . . . . . . . . . 9
About Payflow Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Recurring Billing Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Overview of Recurring Billing Actions Using the Payflow SDK . . . . . . . . . . . . . . . 10
Overview of the Payflow Services Interface in PayPal Manager. . . . . . . . . . . . . . . 11
Chapter 2 Using the SDK to Perform Recurring Tasks . . . . . . . . .13
About Recurring Billing Profile Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Action and Parameter Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Using the Add Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Adding a New Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Example Add Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Example Response for the Add Action . . . . . . . . . . . . . . . . . . . . . . . . . 16
Required Parameters for the Add Action. . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Optional Parameters for the Add Action . . . . . . . . . . . . . . . . . . . . . . . . . 19
Response Values for the Add Action . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Using the Modify and Reactivate Actions . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Example Modify Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Example Reactivate Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Example Response to a Modify or Reactivate Action . . . . . . . . . . . . . . . . . . 22
Required Parameters for the Modify and Reactivate Actions . . . . . . . . . . . . . . . . 22
Optional Parameters for the Modify and Reactivate Actions . . . . . . . . . . . . . . 22
Returned Values for the Modify or Reactivate Actions . . . . . . . . . . . . . . . . . 26
Payflow Pro Recurring Billing Service User’s Guide July 2011 3
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 . . . . . . . . . . . . . . . . . . . . . . . . . 27
Using the Inquiry Action to View Information for a Profile . . . . . . . . . . . . . . . . . . 27
Using the Inquiry Action to View the Status of the Profile . . . . . . . . . . . . . . . . . . 28
Example Profile Status Inquiry Action . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Example Response to a Profile Status Inquiry Action . . . . . . . . . . . . . . . . . . 28
Required Parameters for the Profile Status Inquiry Action. . . . . . . . . . . . . . . . 29
Response Values for the Profile Status Inquiry Action. . . . . . . . . . . . . . . . . . 29
Using the Inquiry Action to View the Status of Payments . . . . . . . . . . . . . . . . . . 31
Using the Inquiry Action to view Recurring Transaction Details . . . . . . . . . . . . . 31
Using the Inquiry Action to View Optional Transaction Details . . . . . . . . . . . . . 32
Required Parameters for the Status of Payments Inquiry Action. . . . . . . . . . . . . . . 33
Return Values for a Status of Payments Inquiry Action . . . . . . . . . . . . . . . . . 33
Using the Payment Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Example Payment Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Example Response to the Payment Action . . . . . . . . . . . . . . . . . . . . . . . 34
Required Parameters for the Payment Action . . . . . . . . . . . . . . . . . . . . . . . . 35
Returned Values for the Payment Action . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 3 Testing Recurring Billing . . . . . . . . . . . . . . . . . . 37
Testing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Credit Card Numbers Used for Testing. . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Testing Result Value Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Appendix A Obtaining Consent to Bill Customers Using Recurring Billing
39
4 July 2011 Payflow Pro Recurring Billing Service User’s Guide
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.
Audience
This guide assumes that its readers:
Are experienced web or application developers
Have a background in payments services
Are familiar with the contents of Payflow Pro Developer’s Guide
Preface
That document along with this guide are your primary sources of information on
developing payments applications.
Purpose
This guide describes in detail how you can use the Payflow SDK to perform recurring billing
transactions. For details on how to use PayPal Manager – the web-based administration tool
for processing transactions manually, issuing credits, and generating reports, see PayPal
Manager online help.
NOTE: PayPal Manager must be used to send customers email receipts and notifications of
failed transactions.
Organization of This Guide
Chapter 1, “Managing Payflow Services,” provides an overview of the Recurring Billing
functionality available in PayPal Manager and in the Payflow SDK.
Chapter 2, “Using the SDK to Perform Recurring Tasks,” describes the use of the Payflow
SDK to perform recurring transactions.
Chapter 3, “Testing Recurring Billing,” describes how to test recurring transactions.
Payflow Pro Recurring Billing Service User’s Guide July 2011 5
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. Payflow Pro is pre-integrated with leading e-commerce solutions and is also
available as a downloadable SDK. This guide contains:
– Detailed descriptions of the Payflow Pro transaction parameters
– Error code information
– Testing information
See the Payflow ACH Payment Service Guide for details on ACH payment processing.
All of the above Payflow documentation can be found on the PayPal Developer Central
website.
See PayPal Manager online help for details on how to use PayPal Manager to perform
recurring tasks.
How to Contact Customer Service
For answers to specific questions about PayPal products:
Contact Customer Service at payflow-support@paypal.com.
6 July 2011 Payflow Pro Recurring Billing Service User’s Guide
Revision History
TABLE P.1 Revision History
Date Description
January 2010 Added using Inquiry to view recurring transaction and optional transaction details in a
October 2009 Added support for optional transactions that are used to validate the buyer’s account
August 2009 Added using a Billing Agreement ID to create a PayPal profile with ACTION=A.
December 2008 Removed RETRYING CURRENT PAYMENT value from STATUS parameter in Inquiry
October 2008 Removed incomplete and confusing list of parameters that can be modified in a profile.
June 2008 Updated Preface.
Preface
Revision History
profile. Included example.
information. No amount is passed with this option.
response.
Added ACH as a recurring billing profile that is supported.
Updated description of ACCT parameter.
September 2007 Adapted for Australia
Payflow Pro Recurring Billing Service User’s Guide July 2011 7
Preface
Revision History
8 July 2011 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.
IMPORTANT: 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.
In This Chapter
“About Payflow Services” on page 9
“Recurring Billing Terms” on page 10
“Overview of Recurring Billing Actions Using the Payflow SDK” on page 10
“Overview of the Payflow Services Interface in PayPal Manager” on page 11
About Payflow Services
NOTE: You must obtain each customer’s consent to bill them on an automated schedule.
Appendix A, “Obtaining Consent to Bill Customers Using Recurring Billing” presents
the relevant sections from PayPal’s Merchant Services Agreement.
To configure a customer to be automatically billed on a schedule, you define a recurring
billing profile for that customer . The profile specifies the account to bill, the associated contact
information, the amount to charge each time, the payment period (monthly, weekly, and so
on), and the term (the number of payments) of the agreement.
NOTE: Recurring billing supports credit card and ACH accounts. For details on ACH payment
management, see the Payflow ACH Payment Service Guide on Developer Central.
When you submit the data, PayPal generates the new profile, activates it, and automatically
performs the billing on the specified schedule. As time goes on, the profile stores both the
configuration information that you supplied and the transaction and payment history for the
account. When the term is complete, the profile is mature and no further automated
transactions occur.
When defining the profile, you have the option to perform an initial transaction that differs
from the recurring transaction, for example, to perform a no-charge transaction that validates
the account information or to charge an initial fee. In addition, you can specify how to handle
declined transactions.
You can perform most recurring billing tasks using either PayPal Manager or the Payflow
SDK.
Payflow Pro Recurring Billing Service User’s Guide July 2011 9
Managing Payflow Services
1
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
Payment Period One payment is made per payment period; for example, a $42 payment
Profile Your definition of a recurring transaction for a single customer. The
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. Once a transaction succeeds
for a payment period, the payment is marked as successful.
on a monthly basis. In this example, the payment period is monthly.
profile includes all information required to automatically bill the right
person the right amount of money at the right time for the right period
of time.
Profile ID Twelve-character string (generated by PayPal) that uniquely identifies a
recurring profile. Test profile IDs start with the characters RT and live
profile IDs, with RP.
Term Total number of payment periods over the duration of the agreement.
For example, a three-year, monthly payment contract has a term of 36.
Term defines the number of scheduled payment periods, not the
payments actually made.
Mature Profile Reference to a profile with a completed term (the total number of
payment periods for the profile have occurred). The fact that a profile is
mature does not necessarily mean that the customer has made all
scheduled payments.
Overview of Recurring Billing Actions Using the Payflow SDK
The Payflow SDK supports several actions that enable you to manage recurring payment
accounts. See Chapter 2, “Using the SDK to Perform Recurring Tasks,” for details on
performing the following supported actions:
Add (ACTION=A)
Add a new recurring billing profile either by submitting the required data (credit card number
or PayPal, payment amount, payment period, and so on) or by converting an existing
transaction into a profile. Upon successful creation, PayPal activates the profile, performs the
optional initial transaction if specified, initiates the payment cycle, and returns a Profile ID.
10 July 2011 Payflow Pro Recurring Billing Service User’s Guide
Managing Payflow Services
Overview of the Payflow Services Interface in PayPal Manager
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.
Inquiry (ACTION=I)
Inquire about the status of a profile and its payment and transaction history.
Payment (ACTION=P)
Perform a real-time retry on a previously failed transaction.
Overview of the Payflow Services Interface in PayPal Manager
1
PayPal Manager enables you to create and manage recurring billing tasks. See PayPal
Manager online help for details on how to perform the following supported tasks:
Adding a profile for a new recurring billing customer
Managing profiles
Configuring optional email messages
Generating reports
Payflow Pro Recurring Billing Service User’s Guide July 2011 11
Managing Payflow Services
1
Overview of the Payflow Services Interface in PayPal Manager
12 July 2011 Payflow Pro Recurring Billing Service User’s Guide
2
Using the SDK to Perform Recurring Tasks
NOTE: 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. You
have the option of performing most recurring billing tasks either from PayPal Manager or
from your code using the Payflow SDK. You must, however, configure email settings using
PayPal Manager, as described in PayPal Manager online help.
IMPORTANT: You must have prior authorization from the customer to bill on a schedule.
See Appendix A, “Obtaining Consent to Bill Customers Using Recurring
Billing,” for additional details.
In This Chapter
“About Recurring Billing Profile Actions” on page 13
“Using the Add Action” on page 14
“Using the Modify and Reactivate Actions” on page 21
“Using the Cancel Action” on page 26
“Using the Inquiry Action to View Information for a Profile” on page 27
“Using the Inquiry Action to View the Status of Payments” on page 31
“Using the Payment Action” on page 34
About Recurring Billing Profile Actions
ACTION operations in the Payflow SDK manipulate profiles (add, modify, reactivate, cancel,
and inquire about status) and submit manual retry requests for failed transactions.
Action and Parameter Definitions
Table 2.1 shows how ACTION values are defined in this document.
TABLE 2.1 Action value definitions
ACTION Value Description
Add A Create a new profile. See “Using the Add Action” on page 13.
Payflow Pro Recurring Billing Service User’s Guide July 2011 13
Loading...