# Payflow Recurring Billing Service User's Guide (/api/nvp-soap/payflow/recurring-billing) ## Contents [#contents] Contents of the PayPal Payflow Gateway Recurring Billing guide are described below. ### This Guide [#this-guide] This guide describes how to use the [Payflow SDK](https://github.com/paypal/payflow-gateway) 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 [#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 the [Payflow Gateway Developer Guide and Reference](/api/nvp-soap/payflow/integration-guide/). That document along with this guide are your primary sources of information on developing payments applications. ### Purpose [#purpose] This guide describes how to use the [Payflow SDK](https://github.com/paypal/payflow-gateway) to perform recurring billing transactions. For details on how to use [PayPal Manager](https://manager.paypal.com) – the web-based administration tool for processing transactions manually, issuing credits, and generating reports, see [PayPal Manager](https://manager.paypal.com) online help. > **Note:** **Note:** PayPal Manager must be used to send customers email receipts and > notifications of failed transactions. ### Organization of This Guide [#organization-of-this-guide] * [Managing Payflow Services](#managing-payflow-services) — provides an overview of the Recurring Billing functionality available in [PayPal Manager](https://manager.paypal.com) and in the [Payflow SDK](https://github.com/paypal/payflow-gateway). * [Using the SDK to Perform Recurring Tasks](#using-the-sdk-to-perform-recurring-tasks) — describes the use of the [Payflow SDK](https://github.com/paypal/payflow-gateway) to perform recurring transactions. * [Testing Recurring Billing](#testing-recurring-billing) — describes how to test recurring transactions. * Appendix [Obtaining Consent to Bill Customers Using Recurring Billing](#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 [#where-to-go-for-more-information] [Payflow Gateway Developer Guide and Reference](/api/nvp-soap/payflow/integration-guide/) Describes the Payflow Gateway, a high performance TCP/IP-based Internet payment gateway solution. Payflow is pre-integrated with leading e-commerce solutions and is also available as a downloadable [Payflow SDK](https://github.com/paypal/payflow-gateway). This guide contains: * Detailed descriptions of the Payflow transaction parameters * Error code information * Testing information See the Payflow ACH Payment Service Guide for details on the ACH payment processing. All the Payflow documentation can be found on the PayPal developer website. See [PayPal Manager](https://manager.paypal.com) online help for details on how to use [PayPal Manager](https://manager.paypal.com) to perform recurring tasks. ### How to Contact Customer Service [#how-to-contact-customer-service] For answers to specific questions about PayPal products: * Email Payflow support at [payflow-support@paypal.com](mailto:payflow-support@paypal.com). * Call Payflow support at 1-888-883-9770. ### Revision History [#revision-history] | Date | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | September 2020 | Added note under Add (`ACTION=A`) about limitation of number of active profiles that can be created in the **pilot environment**. The limit is now 100 active profiles. Added note to `TERM` that the maximum number of times a profile can run in the **pilot environment** is 10 regardless of the value `TERM` is set to. | | August 2020 | Added missing `NUMRETRYDAYS` to the modify function. | | December 2019 | Added missing parameters in profile inquiry response. | | October 2019 | Modified legacy billing parameters; `STREET`, `CITY`, `ZIP`, etc. to BILLTO versions; `BILLTOSTREET`, `BILLTOCITY`, `BILLTOZIP`,etc. | | October 2014 | Added the HTML version of this guide.
Updated description of the `PAYPERIOD` value `SMMO`, used for semi-monthly recurring billing. | | November 2013 | Added a new method for updating recurring billing credit card information. Using the Modify action, merchants can replace credit card information in a recurring billing profile with information from an existing transaction. See [Modifying Account Information Using an Existing Transaction](#modifying-account-information-using-an-existing-transaction) for details.
Added the `DAYS` value to the `PAYPERIOD` field; also, added the `FREQUENCY` field, which is required when `PAYPERIOD=DAYS` to specify the number of days between payments. See [Required Parameters for the Add Action](#required-parameters-for-the-add-action) and [Optional Parameters for the Modify and Reactivate Actions](#optional-parameters-for-the-modify-and-reactivate-actions). Also, Updated URLs that lead to other guides. | | March 2013 | Maintenance release. | | December 2012 | Updated description of `RETRYNUMDAYS` parameter. | | January 2010 | Added using Inquiry to view recurring transaction and optional transaction details in a profile. Included an 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. | | August 2009 | Added using a Billing Agreement ID to create a PayPal profile with `ACTION=A`. | | December 2008 | Removed `RETRYING CURRENT PAYMENT` value from the `STATUS` parameter in an Inquiry response. | | October 2008 | Removed incomplete and confusing list of parameters that can be modified in a profile. Added ACH as a recurring billing profile that is supported. | | June 2008 | Updated Preface. Updated the description of the `ACCT` parameter. | | September 2007 | Adapted for Australia | ## Managing Payflow Services [#managing-payflow-services] This chapter provides a high-level overview of the tasks you can perform using [PayPal Manager](https://manager.paypal.com) and the [Payflow SDK](https://github.com/paypal/payflow-gateway). You must have prior authorization from the customer to bill on an automated schedule. See the Appendix, [Obtaining Consent to Bill Customers Using Recurring Billing](#obtaining-consent-to-bill-customers-using-recurring-billing), for additional details. ### In This Section [#in-this-section] * [About Payflow Services](#about-payflow-services) * [Recurring Billing Terminology](#recurring-billing-terminology) * [Overview of Recurring Billing Actions Using the Payflow SDK](#overview-of-recurring-billing-actions-using-the-payflow-sdk) * [Overview of the Payflow Services Interface in PayPal Manager](#overview-of-the-payflow-services-interface-in-paypal-manager) ### About Payflow Services [#about-payflow-services] > **Note:** **Note:** You must obtain each customer's consent to bill them on an automated schedule. The Appendix, [Obtaining Consent to Bill Customers Using Recurring Billing](#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:** **Note:** Recurring billing supports credit card and ACH accounts. For details on ACH payment management, see the [Payflow ACH Payment Service Guide](https://www.paypalobjects.com/webstatic/en_US/developer/docs/pdf/pp_achpayment_guide.pdf), which is available on the [PayPal developer website](/api/nvp-soap/payflow/integration-guide/). ACH only available to current ACH merchants. Payflow is no longer offering new accounts for ACH. 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](https://manager.paypal.com) or the [Payflow SDK](https://github.com/paypal/payflow-gateway). ### Recurring Billing Terminology [#recurring-billing-terminology] The following describes terms you should be familiar with when using the Recurring Billing Service. | 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. Once a transaction succeeds for a payment period, the payment is marked as successful. | | Payment Period | One payment is made per payment period; for example, a $42 payment on a monthly basis. In this example, the payment period is monthly. | | Profile | Your definition of a recurring transaction for a single customer. The profile includes all information required to automatically bill the right person, for the right amount of money, at the right time, and 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.
**Pilot environment restrictions**: Profile will only run for a maximum number of 10 times regardless of the value of `TERM`. | | 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 [#overview-of-recurring-billing-actions-using-the-payflow-sdk] The [Payflow SDK](https://github.com/paypal/payflow-gateway) supports several actions that enable you to manage recurring payment accounts. See [Using the SDK to Perform Recurring Tasks](#using-the-sdk-to-perform-recurring-tasks) for details on performing the following supported actions: #### Add (ACTION=A) [#add-actiona] Add a new recurring billing profile either by submitting the required data (credit card number or PayPal account, 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. > **Note:** **Pilot Environment Restriction:** Profile creation is limited to 100 active profiles in the pilot environment. Should you attempt to create more than 100 active profiles, you will receive the following error: `RESULT=31&RESPMSG=Error in adding the recurring profile. Maximum number of active profiles in pilot environment reached.` #### Modify (ACTION=M) [#modify-actionm] Modify any setting in the profile. You have the option to run an Optional Transaction. #### Reactivate (ACTION=R) [#reactivate-actionr] Reactivate the specified inactive profile. You specify a new start date and have the option to alter any other profile parameter. #### Cancel (ACTION=C) [#cancel-actionc] Deactivate the recurring profile. PayPal records the cancellation date. #### Inquiry (ACTION=I) [#inquiry-actioni] Inquire about the status of a profile and its payment and transaction history. #### Payment (ACTION=P) [#payment-actionp] Perform a real-time retry on a previously failed transaction. ### Overview of the Payflow Services Interface in PayPal Manager [#overview-of-the-payflow-services-interface-in-paypal-manager] [PayPal Manager](https://manager.paypal.com) enables you to create and manage recurring billing tasks. See [PayPal Manager](https://manager.paypal.com) 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 ## Using the SDK to Perform Recurring Tasks [#using-the-sdk-to-perform-recurring-tasks] > **Note:** **Note:** You should be familiar with the [Payflow SDK](https://github.com/paypal/payflow-gateway) to use the information presented in this chapter. See the [Payflow Gateway Developer Guide and Reference](/api/nvp-soap/payflow/integration-guide/) for full documentation on the SDK. The [Payflow SDK](https://github.com/paypal/payflow-gateway) operations described in this chapter are available only to merchants with Payflow services. This chapter describes the use of the [Payflow SDK](https://github.com/paypal/payflow-gateway) to perform recurring transactions. You have the option of performing most recurring billing tasks either from [PayPal Manager](https://manager.paypal.com) or from your code using the [Payflow SDK](https://github.com/paypal/payflow-gateway). You must, however, configure email settings using [PayPal Manager](https://manager.paypal.com), as described in [PayPal Manager](https://manager.paypal.com) online help. You must have prior authorization from the customer to bill on a schedule. See the Appendix, [Obtaining Consent to Bill Customers Using Recurring Billing](#obtaining-consent-to-bill-customers-using-recurring-billing), for additional details. ### In This Section [#in-this-section-1] * [About Recurring Billing Profile Actions](#about-recurring-billing-profile-actions) * [Using the Add Action](#using-the-add-action) * [Using the Modify and Reactivate Actions](#using-the-modify-and-reactivate-actions) * [Using the Cancel Action](#using-the-cancel-action) * [Using the Inquiry Action to View Information for a Profile](#using-the-inquiry-action-to-view-information-for-a-profile) * [Using the Inquiry Action to View the Status of Payments](#using-the-inquiry-action-to-view-the-status-of-payments) * [Using the Payment Action](#using-the-payment-action) ### About Recurring Billing Profile Actions [#about-recurring-billing-profile-actions] `ACTION` operations in the [Payflow SDK](https://github.com/paypal/payflow-gateway) manipulate profiles (add, modify, reactivate, cancel, and inquire about status) and submit manual retry requests for failed transactions. #### Action and Parameter Definitions [#action-and-parameter-definitions] The following table shows how `ACTION` values are defined in this document. | ACTION | Value | Description | | ---------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Add | `A` | Create a new profile. [Using the Add Action](#using-the-add-action) | | 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](#using-the-modify-and-reactivate-actions) | | Reactivate | `R` | Reactivate an inactive profile. See [Using the Modify and Reactivate Actions](#using-the-modify-and-reactivate-actions) | | Cancel | `C` | Deactivate an existing profile. See [Using the Cancel Action](#using-the-cancel-action) | | Inquiry | `I` | Each customer's profile stores both the configuration information that you supplied with the Add or Modify action and the transaction and payment history for the customer's account. The Inquiry action enables you to view either of the following sets of data about a customer: [Status of a customer's profile](#using-the-inquiry-action-to-view-information-for-a-profile) [Details of each payment for a profile](#using-the-inquiry-action-to-view-the-status-of-payments) | | Payment | `P` | Retry a previously failed payment. [Using the Payment Action](#using-the-payment-action) | ### Using the Add Action [#using-the-add-action] You can Add (`ACTION=A`) a new recurring profile either by submitting the data that defines the profile or by converting an existing transaction into a profile. Upon successful creation of a profile, PayPal activates the profile, performs the *Optional Transaction*, if specified, initiates the payment cycle, and returns a Profile ID. Upon failure, PayPal does not generate the profile and returns an error message. > **Note:** **Pilot Environment Restriction:** Profile creation is limited to 100 active profiles in the pilot environment. Should you attempt to create more than 100 active profiles, you will receive the following error: `RESULT=31&RESPMSG=Error in adding the recurring profile. Maximum number of active profiles in pilot environment reached.` #### Adding a New Profile [#adding-a-new-profile] To create a new profile: Provide all required data and specify whether to perform an *Optional Transaction*. The *Optional Transaction* is either of the following: * A Sale transaction for an amount that you specify (typically an account start-up fee) * 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 or account verification.) 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. **To convert an existing transaction into a profile:** Specify the `PNREF` of the transaction to use it as a template, and optionally supply additional payment data. You can use only a Sale or Delayed Capture transaction as a template for a profile. You can specify values for the following transaction parameters in an Add action: `BILLTOFIRSTNAME` `BILLTOMIDDLENAME` `BILLTOLASTNAME` `BILLTOSTREET` `BILLTOCITY` `BILLTOSTATE` `BILLTOZIP` `BILLTOCOUNTRY` `BILLTOPHONENUM` `BILLTOEMAIL` `SHIPTOFIRSTNAME` `SHIPTOMIDDLENAME` `SHIPTOLASTNAME` `SHIPTOSTREET` `SHIPTOCITY` `SHIPTOSTATE` `SHIPTOZIP` `SHIPTOCOUNTRY` `COMMENT1` `COMPANYNAME` > **Note:** **Note:** Values of processor-specific parameters are forwarded and stored, but do not appear in reports. #### Example Add Actions [#example-add-actions] **Adding a New Profile for a Credit Card Account** The following example Payflow parameter string creates a recurring billing profile that bills a credit card account. Parameters are described in [Required Parameters for the Add Action](#required-parameters-for-the-add-action) and [Optional Parameters for the Add Action](#optional-parameters-for-the-add-action).
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4&ACTION=A &PROFILENAME=RegularSubscription&AMT=42.00&ACCT=4012888888881881&EXPDATE=0203 &START=12012013&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. Parameters are described in [Required Parameters for the Add Action](#required-parameters-for-the-add-action) and [Optional Parameters for the Add Action](#optional-parameters-for-the-add-action).
```text lineNumbers TRXTYPE=R&TENDER=P&PARTNER=PayPal&USER=Acme&PWD=test1234&ACTION=A &PROFILENAME=RegularSubscription&AMT=4.46&BAID=B-29X12812Y7908851G &START=09252013&PAYPERIOD=WEEK&TERM=12&OPTIONALTRX=A&MAXFAILPAYMENTS=1 &RETRYNUMDAYS=1&CURRENCY=USD ``` **Converting an Existing Transaction Into a Profile** The following example Payflow parameter string creates a profile for an original transaction that had a `PNREF<` value of xyz123 and specifies a payment amount of $42. You must set the `ORIGID` value to the original transaction's `PNREF` value. Parameters are described in [Required Parameters for the Add Action](#required-parameters-for-the-add-action) and [Optional Parameters for the Add Action](#optional-parameters-for-the-add-action).
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4&ACTION=A &PROFILENAME=RegularSubscription&ORIGID=XYZ123&START=12012013&PAYPERIOD=WEEK&TERM=12 &OPTIONALTRX=S&OPTIONALTRXAMT=2.00&COMMENT1=First-time customer&AMT=42.00 ``` #### Example Response for the Add Action [#example-response-for-the-add-action] The following is an example response for the Add Action. Returned values are described in [Response Values for the Add Action](#response-values-for-the-add-action)
```text lineNumbers RESULT=0&RPREF=RWY504915344&PROFILEID=RP000000001234&RESPMSG=Approved&TRXRESULT=0 &TRXPNREF=VWYA04915345&TRXRESPMSG=Approved&AUTHCODE=489PNI ``` #### Required Parameters for the Add Action [#required-parameters-for-the-add-action] The following parameters are required for the Add action: | Parameter | Description | Usage (length) | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `TRXTYPE` | Specifies a recurring profile request.
| Must be `R`.
| | `TENDER` | Tender type. Is one of the following values:
`C`. Credit card.`P`. PayPal.`A`. Automated Clearinghouse (ACH). | Must be a one-character value. A valid value is`C`, `P`, or `A`.
| | `ACTION` | Add, Modify, Cancel, Reactivate, Inquiry, or Payment.
| Must be `A` (one character).
| | `PROFILENAME` | A user-specified name for the profile. Can be used to search for a profile.
| Non-unique identifying text name; Alphanumeric (128).
| | `ACCT` | Required with `TENDER=C` or `TENDER=A`. Can be used to search for a profile.
> **Note:** **Note:** For a credit card profile, be sure to use a valid credit card number. If necessary, perform an Authorization with a zero-dollar amount to verify the credit card. | Alphaumeric (19 characters).
| | `BAID` | Is the billing agreement ID returned in the Do Express Checkout Payment or Create Customer Billing Agreement response. To get and update BAIDs, see the [Express Checkout for Payflow Guide](/api/nvp-soap/payflow/express-checkout/).
> **Note:** **Note:** Either a `BAID` or `ORIGID`(`PNREF`) returned from the original transaction used to create a new profile is required when `TENDER=P`. | Alphaumeric (19 characters).
| | `ORIGID` | The `PNREF` value (length=12) returned from the original transaction used to create a new profile.
> **Note:** **Note:** Either a BAID or ORIGID is required to create a new profile when `TENDER=P`. | Alphaumeric (19 characters).
| | `AMT` | Dollar amount (US dollars) to be billed. 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.
| Numeric (ten characters including the decimal point).
| | `START` | Beginning date for the recurring billing cycle used to calculate when payments should be made. Use tomorrow's date or a date in the future.
| Format: `MMDDYYYY`. Numeric (eight characters).
| | `TERM` | Number of payments to be made over the life of the agreement. A value of `0` means that payments should continue until the profile is deactivated.
**Pilot environment restrictions**: Profile will only run for a maximum number of 10 times regardless of the value of `TERM`.
| Numeric.
| | `PAYPERIOD` | Specifies how often the payment occurs:
`DAYS`: Number of days between payments. Must be used with `FREQUENCY`. For example, if `FREQUENCY=100`, a payment is collected once every 100 days. If the `FREQUENCY`field is not passed, the default frequency value is 1, and the customer is billed on a daily basis.
`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 - Once every 15 or 16 days, depending on the number of days in the month. Results in 24 payments per year. If the first payment takes place between the 1st and the 15th of the month, the second payment happens 15 or 16 days later.
`FRWK`: Every Four Weeks - Every 28 days from the previous payment date beginning with the first payment date. Results in 13 payments per year.
`MONT`: Monthly - Every month on the same date as the first payment. Results in 12 payments per year.
`QTER`: Quarterly - Every three months on the same date as the first payment.
`SMYR`: Twice Every Year - Every six months on the same date as the first payment.
`YEAR`: Yearly - Every 12 months on the same date as the first payment.
| Must be a value shown here, including all uppercase letters (four characters).
| | `FREQUENCY` | Use if `PAYPERIOD=DAYS`to set the number of days between payments. For example, if`FREQUENCY=100`, a payment is collected once every 100 days. If `FREQUENCY` is not passed with `PAYPERIOD=DAYS`, it defaults to the value `1` and the customer is billed on a daily basis. If `FREQUENCY` is passed without `PAYPERIOD=DAYS`, the transaction fails.
| Numeric (ten characters).
| #### Optional Parameters for the Add Action [#optional-parameters-for-the-add-action] | Parameter | Description | Usage (length) | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `ORIGID` | `PNREF` value (length=12) of the original transaction used to create a profile.
> **Note:** **Note:** `ORIGID` is optional when`TENDER=C` or `TENDER=A`. | Alphaumeric (19 characters).
| | `MAXFAILPAYMENTS` | The number of payment periods (as specified by`PAYPERIOD`) for which the transaction is allowed to fail before PayPal cancels a profile. These periods need not be consecutive (for example, if payments fail in January, March, and June, the profile is canceled).
If you specify `3`, PayPal allows a maximum of three failed payment periods (possibly with multiple retries during each payment period, and possibly non-consecutive periods). If the transaction is not approved for any three periods (months in the example), PayPal deactivates the profile.
> **Note:** **Important:** If you do not specify a value, the default value of `0` (zero) specifies no limit. Retry attempts occur until the term is complete. | Default is: `0`.
| | `RETRYNUMDAYS` | The number of consecutive days that PayPal should attempt to process a failed transaction until Approved status is received; maximum value is `4`.
| Numeric.
| | `BILLTOEMAIL` | Customer email address. This value is used when sending email receipts to customers.
| Alphanumeric (120 characters).
| | `DESC` | Optional description of the goods or services being purchased. This parameter applies only for ACH\_CCD accounts.
| Alphanumeric (80 characters).
| | `COMPANYNAME` | Company name associated with this profile.
| Alphanumeric (64 characters).
| | `OPTIONALTRX` | Defines an optional Authorization for validating the account information or for charging an initial fee. If this transaction fails, then the profile is not generated. The values are:
`A`: an optional Authorization transaction to verify the account. It applies to credit card transactions only.
`S`: a Sale transaction for an initial fee specified by `OPTIONALTRXAMT`.
| Alphanumeric (one character).
| | `OPTIONALTRXAMT` | Amount of the Optional Transaction. Required only when`OPTIONALTRX=S`.
> **Note:** **Note:** Do not specify an amount when`OPTIONALTRX=A`. The amount is ignored. | | | `BILLTOSTREET` | Billing street.
| | | `BILLTOZIP` | Billing postal code.
| Alphanumeric (ten characters).
| #### Response Values for the Add Action [#response-values-for-the-add-action] The [Payflow Gateway Developer Guide and Reference](/api/nvp-soap/payflow/integration-guide/transaction-responses/#result-values-and-respmsg-text) describes the response values in detail. | Field | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RESULT` | Result value for the action.
| | `PROFILEID` | If RESULT = `0`, this value is the Profile ID. 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.
| #### Returned Values if You Specify an Optional Transaction [#returned-values-if-you-specify-an-optional-transaction] The following table lists values that are included in the response if the transaction involved an optional transaction, such as an account verification or an initial charge. Other payment-related fields could also be returned, depending on your configuration (for example, verbosity level). | Field | Description | | ------------ | -------------------------------------- | | `TRXPNREF` | `PNREF` of the optional transaction. | | `TRXRESULT` | `RESULT` of the optional transaction. | | `TRXRESPMSG` | `RESPMSG` of the optional transaction. | ### Using the Modify and Reactivate Actions [#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. > **Note:** **Note:** The Modify action cannot reactivate a profile that PayPal canceled. The Modify action can also be used to update credit card account information using information from an existing transaction. This is done by passing the `PNREF` of the existing transaction in the ORIGID field. Additionally, the Modify action is useful, for example, when an inactive customer wishes to restart payments using a new valid credit card. The Modify action changes a profile's `STATUS` to active but does not change the `START` date. To change the `START` date, use the Reactivate command (`ACTION=R`). Profile `STATUS` is described in [Response Values for the Profile Status Inquiry Action](#response-values-for-the-profile-status-inquiry-action). You can Reactivate (`ACTION=R`) a profile with inactive `STATUS`. (Profiles can be deactivated for the following reasons: the term has completed, the profile reached maximum allowable payment failures, or you canceled the profile.) You have the option to alter any profile parameter, including an Optional Transaction, and you must specify a new start date. > **Note:** **Note:** Values of processor-specific parameters are forwarded and stored, but do not appear in reports. #### Example Modify Action [#example-modify-action] **Modifying the Payment Amount** The following example Payflow parameter string uses the Modify (`ACTION=M`) action to change the amount of payment to $42.00 (`AMT=42.00`) for profile ID number `RP0000001234`.
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4 &ACTION=M&AMT=42.00&ORIGPROFILEID=RP0000001234 ``` Parameters are described in [Required Parameters for the Modify and Reactivate Actions](#required-parameters-for-the-modify-and-reactivate-actions). **Modifying the Account Expiration Date** The following example Payflow parameter string uses the Modify (`ACTION=M`) action to change the account expiration date (`EXPDATE=0115`) for profile ID number `RP0000001234`.
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4 &ACTION=M&EXPDATE=0115&ORIGPROFILEID=RP0000001234 ``` Parameters are described in [Required Parameters for the Modify and Reactivate Actions](#required-parameters-for-the-modify-and-reactivate-actions). ##### Modifying Account Information Using an Existing Transaction [#modifying-account-information-using-an-existing-transaction] The following example Payflow parameter string uses the Modify (`ACTION=M`) action to copy credit card account information from an existing transaction, using the transaction `PNREF` (`ORIGID=ABBC7D16J6H3`), to profile ID number `RP0000001234`.
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4&ACTION=M &ORIGID=ABBC7D16J6H3&ORIGPROFILEID=RP0000001234 ``` Parameters are described in [Required Parameters for the Modify and Reactivate Actions](#required-parameters-for-the-modify-and-reactivate-actions). #### Example Reactivate Action [#example-reactivate-action] Payments missed while a profile is inactive are not re-tried if you reactivate the profile after the missed payment periods have passed. To submit the missed payment transactions, you must reactivate the profile and increase the value of either `TERM` or `MAXFAILPAYMENTS`. Alternatively, perform a manual payment using [PayPal Manager](https://manager.paypal.com) – the profile is activated as a side effect of the manual payment. The following example Payflow parameter string performs a Reactivate action. Parameters are described in [Required Parameters for the Modify and Reactivate Actions](#required-parameters-for-the-modify-and-reactivate-actions).
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4&ACTION=R &ACCT=4012888888881881&START=11082013&VERBOSITY=HIGH ``` #### Example Response to a Modify or Reactivate Action [#example-response-to-a-modify-or-reactivate-action] The following is an example of a successful response to a Modify or Reactivate action. Returned values are described in [Returned Values for the Modify or Reactivate Actions](#returned-values-for-the-modify-or-reactivate-actions).
```text lineNumbers RESULT=0&RPREF=RWY504915344&PROFILEID=RP000000001234&RESPMSG=Approved&TRXRESULT=0 &TRXPNREF=VWYA04915345&TRXRESPMSG=Approved&AUTHCODE=489PNI ``` To verify any modifications made to a recurring billing profile, see [Using the Inquiry Action to View Information for a Profile](#using-the-inquiry-action-to-view-information-for-a-profile). #### Required Parameters for the Modify and Reactivate Actions [#required-parameters-for-the-modify-and-reactivate-actions] The following table shows required parameters for the Modify and Reactive actions. | Parameter | Description | Usage (length) | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `TRXTYPE` | Specifies a recurring profile request.
| Must be `R` (one character).
| | `ACTION` | Specifies Action type: Modify (`M`) or Reactivate (`R`).
| Must be `M` or `R` (one character).
| | `TENDER` | Tender type. Is one of the following values:
`C`. Credit card.`P`. PayPal.`A`. Automated Clearinghouse (ACH). If the transaction is a PayPal transaction with a `BAID`, be sure to include `TENDER=P` in the request. | Must be `C`, `P`, or `A` (one character).
| | `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`.
| | #### Optional Parameters for the Modify and Reactivate Actions [#optional-parameters-for-the-modify-and-reactivate-actions] The following parameters do not need to be changed or added for a Modify or Reactivate action. | Parameter | Description | Usage (length) | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `PROFILENAME` | Name for the profile (you specify the name). Can be used to search for a profile. Non-unique identifying text name. | Alphanumeric (128 characters). | | `ACCT` | Can be used to search for a profile. | Numeric (19 characters). | | `CURRENCY` | One of the following three-character currency codes listed in the[Payflow Gateway Developer Guide and Reference](/api/nvp-soap/payflow/integration-guide/). > **Note:** **Note:** `CURRENCY` is applicable only to processors that support transaction-level currency. | Numeric (3 characters). | | `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`. | | | `ORIGID` | Is the PNREF value (length=12) of an original transaction used to update credit card account information.
> **Note:** **Note:** Optional only for `TENDER=C`. | Alphaumeric (19 characters). | | `AMT` | Dollar amount to be billed. Can be used to search for a profile. 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. | Numeric (10 with decimal point). | | `EXPDATE` | Account expiration date. Format: `MMYY`. | Numeric (4 characters). | | `START` | Beginning (or restarting) date for the recurring billing cycle used to calculate when payments should be made. Use tomorrow's date or a date in the future Format: `MMDDYYYY`. For`ACTION=Modify`, this is used to speed up or delay only the next payment date. If a new `PAYPERIOD` is specified, then this is also the time that the next payment is made. | Numeric (8 characters). | | `TERM` | Number of payments to be made over the life of the agreement. A value of `0` means that payments should continue until the profile is deactivated.
**Pilot environment restrictions**: Profile will only run for a maximum number of 10 times regardless of the value of `TERM`.
| Numeric. | | `PAYPERIOD` | Specifies how often the payment occurs.
> **Note:** **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 follows:
`DAYS`: Number of days between payments. Must be used with `FREQUENCY`. For example, if`FREQUENCY=100`, a payment is collected once every 100 days. If the `FREQUENCY` field is not passed, the default frequency value is 1, and the customer is billed on a daily basis.
`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 - Once every 15 or 16 days, depending on the number of days in the month. Results in 24 payments per year. If the first payment takes place between the 1st and the 15th of the month, the second payment happens 15 or 16 days later.
`FRWK`: Every Four Weeks - Every 28 days from the previous payment date beginning with the first payment date. Results in 13 payments per year.
`MONT`Monthly - Every month on the same date as the first payment. Results in 12 payments per year.
`QTER`: Quarterly - Every three months on the same date as the first payment.
`SMYR`: Twice Every Year — Every six months on the same date as the first payment.
`YEAR`: Yearly - Every 12 months on the same date as the first payment.
| Must be a value shown here, including all uppercase letters (4 characters).
| | `RETRYNUMDAYS` | The number of consecutive days that PayPal should attempt to process a failed transaction until Approved status is received; maximum value is 4. | Numeric (1 character). | | `FREQUENCY` | Use if `PAYPERIOD=DAYS` to set the number of days between payments. For example, if `FREQUENCY=100`, a payment is collected once every 100 days. If `FREQUENCY` is not passed with `PAYPERIOD=DAYS`, it defaults to the value `1` and the customer is billed on a daily basis. If `FREQUENCY` is passed without `PAYPERIOD=DAYS`, the transaction fails. | Numeric (ten characters). | | `MAXFAILPAYMENTS`
| The number of payment periods (as specified by `PAYPERIOD`) for which the transaction is allowed to fail before PayPal cancels a profile. These periods need not be consecutive (for example, if payments fail in January, March, and June, the profile is canceled). 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 non-consecutive periods). If the transaction is not approved for any three periods (months in the example), then PayPal deactivates the profile. > **Note:** **Important:** Even though this parameter is optional, if you do not specify a value, the default value of `0` (zero) specifies that retry attempts should occur until the term is complete. | Numeric; Default is `0`. | | `BILLTOEMAIL` | 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.
> **Note:** **Important:** You must specify additional text for the message using [PayPal Manager](https://manager.paypal.com). For details, see \[[PayPal Manager online help](https://manager.paypal.com). | Alphanumeric (120 characters). | | `COMPANYNAME` | Company name associated with this profile. | Alphanumeric (64 characters). | | `OPTIONALTRX` | Defines an optional Authorization for validating the account information or for charging an initial fee. If this transaction fails, then the profile is not generated. The values are:
`A`: an optional Authorization transaction to verify the account. It applies to credit card transactions only.
`S`: a Sale transaction for an initial fee specified by `OPTIONALTRXAMT`.
| Alphanumeric (one character).
| | `OPTIONALTRXAMT` | Amount of the Optional Transaction. Required only when `OPTIONALTRX=S`.
> **Note:** **Note:** Do not specify an amount when `OPTIONALTRX=A`. The amount is ignored. . | | | `BILLTOSTREET` | Billing address.
| Alphanumeric (150 characters).
| | `BILLTOZIP` | Billing zip code.
| Alphanumeric (ten characters).
| #### Returned Values for the Modify or Reactivate Actions [#returned-values-for-the-modify-or-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.
| #### Returned Values if You Specify an Optional Transaction [#returned-values-if-you-specify-an-optional-transaction-1] The following table lists values that are included in the response if the transaction involved an Optional transaction. Other payment-related fields could also be returned, depending on your configuration (for example, verbosity level). | Field | Description | | ------------ | -------------------------------------- | | `TRXPNREF` | `PNREF` of the optional transaction. | | `TRXRESULT` | `RESULT` of the optional transaction. | | `TRXRESPMSG` | `RESPMSG` of the optional transaction. | ### Using the Cancel Action [#using-the-cancel-action] You can Cancel (`ACTION=C`) the recurring profile to deactivate the profile from performing further transactions. The profile is marked as cancelled and the customer is no longer billed. PayPal records the cancellation date. All parameters other than those listed in the example are ignored, and no profile settings are changed when you submit a Cancel action. > **Note:** **Note:** If desired, you can use the Reactivate action to reactivate the profile. #### Example Cancel Action [#example-cancel-action] The following example Payflow parameter string performs a Cancel action. Parameters are described in [Required Parameters for the Cancel Action](#required-parameters-for-the-cancel-action).
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4 &ACTION=C&ORIGPROFILEID=RP000000001234 ``` #### Example Response to the Cancel Action [#example-response-to-the-cancel-action] Returned values are described in [Returned Values for the Cancel Action](#returned-values-for-the-cancel-action).
```text lineNumbers RESULT=0&RPREF=RWY504915344&PROFILEID=RP000000001234&RESPMSG=Approved &TRXRESULT=0&TRXPNREF=VWYA04915345&TRXRESPMSG=Approved&AUTHCODE=489PNI ``` #### Required Parameters for the Cancel Action [#required-parameters-for-the-cancel-action] | Parameter | Description | Usage (length) | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `TRXTYPE` | Specifies a recurring profile request. | Must be `R` (one character). | | `ACTION` | Specifies action to take. | Must be `C` (one character). | | `ORIGPROFILEID` | Profile ID of the profile to cancel. Profile IDs for test profiles start with `RT`. Profile IDs for live profiles start with `RP`. | | #### Returned Values for the Cancel Action [#returned-values-for-the-cancel-action] | 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 Inquiry Action to View Information for a Profile [#using-the-inquiry-action-to-view-information-for-a-profile] You can use the Inquiry action to request two different sets of information for a profile: * To view the full set of payment information (that is, the recurring and optional transaction details), you submit two separate Inquiry actions (see [Using the Inquiry Action to View the Status of Payments](#using-the-inquiry-action-to-view-the-status-of-payments) * To view the recurring transaction details, pass the `PAYMENTHISTORY=Y` name-value pair with the Inquiry action. * 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 Inquiry Action to View the Status of the Profile [#using-the-inquiry-action-to-view-the-status-of-the-profile] See the following examples: #### Example Profile Status Inquiry Action [#example-profile-status-inquiry-action] The following example Payflow parameter string performs a profile status Inquiry action. Parameters are described in [Required Parameters for the Profile Status Inquiry Action](#required-parameters-for-the-profile-status-inquiry-action).
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme &PWD=a1b2c3d4&ACTION=I&ORIGPROFILEID=RP000000001234&VERBOSITY=HIGH ``` #### Example Response to a Profile Status Inquiry Action [#example-response-to-a-profile-status-inquiry-action] The following is an example response to a profile status Inquiry action. Returned values are described in [Response Values for the Profile Status Inquiry Action](#response-values-for-the-profile-status-inquiry-action). > **Note:** **Note:** Transactions sent after the buyer's account has expired return the expiration date or `0000` and fail.
```text lineNumbers RESULT=0&RPREF=R2X52F7AA3E9&PROFILEID=RT0000000278&STATUS=ACTIVE&CREATIONDATE=0410201 5&PROFILENAME=123456789/*&START=04112015&TERM=0&NEXTPAYMENT=12112019&PAYPERIOD=DAYS &LASTCHANGED=12102019&RPSTATE=6&NEXTPAYMENTNUM=1706&COMMENT1=Pass Comment& FREQUENCY=1&TENDER=C&AMT=1.00&ACCT=4012XXXXXXXX1881&EXPDATE=1018&AGGREGATEAMT=1705.00 &AGGREGATEOPTIONALAMT=5.00&MAXFAILPAYMENTS=0&NUMFAILPAYMENTS=0&RETRYNUMDAYS=0& BILLTOEMAIL=customer@email.com&BILLTOFIRSTNAME=Lord&MBILLTOMIDDLENAME=Middle& BILLTOLASTNAME=Nikkon&BILLTOSTREET=123 Main St&BILLTOCITY=Omaha&BILLTOSTATE=NE &BILLTOZIP=12345&BILLTOCOUNTRY=US&BILLTOPHONENUM=403-234-5678&SHIPTOFIRSTNAME=Lord &SHIPTOMIDDLENAME=Middle&SHIPTOLASTNAME=Nikkon&SHIPTOSTREET=123 Testing &SHIPTOCITY=San Jose&SHIPTOSTATE=CA&SHIPTOZIP=67890&SHIPTOCOUNTRY=US ``` #### Required Parameters for the Profile Status Inquiry Action [#required-parameters-for-the-profile-status-inquiry-action] | Parameter | Description | Usage (length) | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `TRXTYPE` | Specifies a recurring profile request. | Must be `R` (one character). | | `ACTION` | Specifies action to take. | Must be `I` (one character). | | `ORIGPROFILEID` | Profile ID of the profile to inquire about. Profile IDs for test profiles start with `RT`. Profile IDs for live profiles start with `RP`. | | #### Response Values for the Profile Status Inquiry Action [#response-values-for-the-profile-status-inquiry-action] An Inquiry action for profile status can return any of the values listed in the following table. Inquiries echo only those name-value pairs sent to the recurring billing server. For example, if, while adding or modifying a profile, you do not assign a value to `PHONENUM`, inquiries about the profile do not return a value for `PHONENUM`. > **Note:** **Note:** See the [Payflow Gateway Developer Guide and Reference](/api/nvp-soap/payflow/integration-guide/submit-transactions/#core-credit-card-parameters) for a list of optional parameters that you can pass for reporting purposes, such as, `COMMENT1`. | Field | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RESULT` | Result value of the profile request. This value represents the success or failure of the Inquiry transaction, not of the financial transaction. | | `PROFILEID` | Request profile reference number. Profile IDs for test profiles start with the characters `RT`. Profile IDs for live profiles start with `RP`. | | `PROFILENAME` | Name of the profile. | | `RESPMSG` | Response message if result value is non-zero. | | `ACCT` | Masked credit card number stored in profile. | | `EXPDATE` | Expiration date of credit card on file. | | `START` | Date of beginning recurring billing cycle. | | `CREATIONDATE` | Date profile was created. | | `LASTCHANGED` | Date of last profile update. | | `TERM` | Total number of payments. | | `PAYPERIOD` | Period of payment recurrence (weekly, monthly, and so on). | | `FREQUENCY` | Number of days (frequency) between payment. Returned if `PAYPERIOD=DAYS`. | | `STATUS` | Current status of the profile. One of the following:
`VENDOR INACTIVE``DEACTIVATED BY MERCHANT``EXPIRED` (if profile is expired, limited profile data is returned)`TOO MANY FAILURES`: PayPal canceled the profile because it has too many failed transactions (for example, as would result with a bad credit card).`ACTIVE` | | `TENDER` | Tender Type. | | `PAYMENTSLEFT` | Number of payments left to be billed.
> **Note:** **Note:** 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. | | `NEXTPAYMENT` | Date that the next payment is due. | | `NEXTPAYMENTNUM` | Number of next payment. | | `END` | Date that the last payment is due. Present only if this is not an unlimited-term subscription. | | `AGGREGATEAMT` | Amount collected so far for scheduled payments. | | `AGGREGATEOPTIONALAMT` | Amount collected through sending optional transactions. | | `AMT` | Base dollar amount to be billed. | | `MAXFAILPAYMENTS` | The number of payment periods (specified by `PAYPERIOD`) for which the transaction is allowed to fail before PayPal cancels a profile. See `RETRYNUMDAYS`. | | `NUMFAILPAYMENTS` | Number of payments that failed. | | `RETRYNUMDAYS` | The number of consecutive days that PayPal should attempt to process a failed transaction until Approved status is received; maximum value is `4`. | | `BILLTOEMAIL` | Customer email address email receipts (described in [PayPal Manager online help](https://manager.paypal.com)). | | `COMPANYNAME` | Recurring Profile Company Name. | | `BILLTOFIRSTNAME` | First name of card holder. | | `BILLTOMIDDLENAME` | Middle name of card holder. | | `BILLTOLASTNAME` | Last name of card holder. | | `BILLTOSTREET` | Billing street. | | `BILLTOCITY` | Billing city. | | `BILLTOSTATE` | Billing state. | | `BILLTOZIP` | Billing postal code. | | `BILLTOCOUNTRY` | Billing country. | | `BILLTOPHONENUM` | Telephone number. | | `SHIPTOFIRSTNAME` | First name of the ship-to person. | | `SHIPTOMIDDLENAME` | Middle name of the ship-to person. | | `SHIPTOLASTNAME` | Last name of the ship-to person. | | `SHIPTOSTREET` | Shipping street. | | `SHIPTOCITY` | Shipping city. | | `SHIPTOSTATE` | Shipping state. | | `SHIPTOZIP` | Shipping postal code. | | `SHIPTOCOUNTRY` | Shipping country. | ### Using the Inquiry Action to View the Status of Payments [#using-the-inquiry-action-to-view-the-status-of-payments] To view the full set of payment information (that is, the recurring and optional transaction details), you submit two separate Inquiry actions: * To view the recurring transaction details, pass the `PAYMENTHISTORY=Y` name-value pair with the Inquiry action. * To view the optional transaction details, pass the `PAYMENTHISTORY=O` name-value pair with the Inquiry action. ### Using the Inquiry Action to view Recurring Transaction Details [#using-the-inquiry-action-to-view-recurring-transaction-details] **Example Status for a Recurring Transaction Details Inquiry Action** The following example Payflow parameter string performs a recurring transaction details Inquiry action. Inquiry action parameters are described in [Required Parameters for the Status of Payments Inquiry Action](#required-parameters-for-the-status-of-payments-inquiry-action).
```text lineNumbers TRXTYPE=R&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4&ACTION=I &PAYMENTHISTORY=Y&ORIGPROFILEID=RT0000001234 ``` **Example Results for a Recurring Transaction Details Inquiry Action** The following is an example response to a recurring transaction details Inquiry action. The data includes only the final payment attempt for each payment period. The characters `P_` are prepended to parameter names to indicate that they represent historical payment data. The number appended to parameter names is the payment number. Returned values are described in [Required Parameters for the Status of Payments Inquiry Action](#required-parameters-for-the-status-of-payments-inquiry-action).
```text lineNumbers 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.00 &P_TRANSTATE3=8&P_PNREF4=VWYA06157668&P_TRANSTIME4=10-Jun-04 04:47 PM &P_RESULT4=0&P_TENDER4=C&P_AMT4=1.00&P_TRANSTATE4=8&P_PNREF5=VWYA06158795 &P_TRANSTIME5=17-Jun-04 04:47 PM&P_RESULT5=0&P_TENDER5=C&P_AMT5=1.00 &P_TRANSTATE5=8&P_PNREF6=VJLA00000060&P_TRANSTIME6=05-Aug-04 05:54 PM &P_RESULT6=0&P_TENDER6=C&P_AMT6=1.00&P_TRANSTATE6=1 ``` #### Using the Inquiry Action to View Optional Transaction Details [#using-the-inquiry-action-to-view-optional-transaction-details] **Example Status for an Optional Transaction Details Inquiry Action** The following example Payflow parameter string performs an optional transaction details Inquiry action. Inquiry action parameters are described in [Required Parameters for the Status of Payments Inquiry Action](#required-parameters-for-the-status-of-payments-inquiry-action).
```text lineNumbers TRXTYPE=R&PARTNER=PayPal&USER=Acme&PWD=a1b2c3d5&ACTION=I&PAYMENTHISTORY=O &ORIGPROFILEID=RP0000000176 ``` **Example Results for an Optional Transaction Details Inquiry Action** The following is an example response to an optional transaction details Inquiry action. The data includes only the final payment attempt for each payment period. The characters `P_` are prepended to parameter names to indicate that they represent historical payment data. The number appended to parameter names is the payment number. Returned values are described in [Return Values for a Status of Payments Inquiry Action](#return-values-for-a-status-of-payments-inquiry-action).
```text lineNumbers RESULT=0&RPREF=RFH50DCFC123&PROFILEID=RP0000000176&P_PNREF3=VFHA0DC47259 &P_TRANSTIME3=11-May-09 12:16 PM&P_RESULT3=0&P_TENDER3=C&P_AMT3=1.97 &P_TRANSTATE3=8&P_PNREF2=VFHA0DC47256&P_TRANSTIME2=11-May-09 12:14 PM &P_RESULT2=0&P_TENDER2=C&P_AMT2=1.97&P_TRANSTATE2=8&P_PNREF1=VFHA0DC4724E &P_TRANSTIME1=11-May-09 12:00 PM&P_RESULT1=0&P_TENDER1=C&P_AMT1=10.97&P_TRANSTATE1=8 ``` #### Required Parameters for the Status of Payments Inquiry Action [#required-parameters-for-the-status-of-payments-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` (one character). | | `TRXTYPE` | Specifies a recurring profile request. | Must be `R` (one character). | | `ACTION` | Specifies action to take. Must be `I` (one character). | | | `ORIGPROFILEID` | Profile ID of the profile to inquire about. Profile IDs for test profiles start with `RT`.Profile IDs for live profiles start with `RP`. | | #### Return Values for a Status of Payments Inquiry Action [#return-values-for-a-status-of-payments-inquiry-action] The return parameter names have the format `P_n`, where the index `n` reflects the payment number, starting at `1`. The values listed in the following table are returned for each payment: | Field | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `P_RESULTn` | Result value of the financial transaction.
> **Note:** **Note:** Only the final result for each payment is returned, so payments that eventually succeed after being retried are returned with `RESULT=0`. | | `P_PNREFn` | `PNREF` of the particular payment. The Payment Network Reference ID value (`PNREF`) is a unique transaction identification number issued by PayPal that identifies the transaction for billing, reporting, and transaction data purposes. The `PNREF` value appears in the Transaction ID column in \[[PayPal Manager](https://manager.paypal.com) reports. | | `P_TRANSTATEn` | `TRANS_STATE` of the particular payment.
`1`: error`6`: settlement pending`7`: settlement in progress`8`: settlement completed / successfully`11`: settlement failed`14`: settlement incomplete. | | `P_TENDERn` | Tender type. | | `P_TRANSTIMEn` | The time stamp 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 [#using-the-payment-action] The Payment action (`ACTION=P`) performs a real-time retry on a transaction that is in the retry state. The response string is similar to the string for Optional transactions, except that, upon approval, the profile is updated to reflect the successful retry. If the transaction being retried is part of the current payment period, a successful Payment action causes the profile to flag the current payment as successful and to advance to the next payment at the scheduled time. If the profile had been previously cancelled due to too many failed payments, then a successful Payment action decrements the failed payment count and re-activates the profile (thus re-starting the recurring payment cycle). #### Example Payment Action [#example-payment-action] The following example Payflow parameter string performs a Payment action. Parameters are described in [Required Parameters for the Payment Action](#required-parameters-for-the-payment-action).
```text lineNumbers TRXTYPE=R&TENDER=C&PARTNER=PayPal&VENDOR=Acme&USER=Acme&PWD=a1b2c3d4 &ACTION=P&ORIGPROFILEID=RP000000001234&AMT=85.00&PAYMENTNUM=13 ``` #### Example Response to the Payment Action [#example-response-to-the-payment-action] The following is an example response to a Payment action. Returned values are described in [Required Parameters for the Payment Action](#required-parameters-for-the-payment-action).
```text lineNumbers RESULT=0&RPREF=RWY504915344&PROFILEID=RP000000001234&RESPMSG=Approved &TRXRESULT=0&TRXPNREF=VWYA04915345&TRXRESPMSG=Approved&AUTHCODE=489PNI ``` ### Required Parameters for the Payment Action [#required-parameters-for-the-payment-action] | Parameter | Description | Usage (length) | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `TRXTYPE` | Specifies a recurring profile request. Must be `R`. | One character. | | `ACTION` | Specifies action to take. Must be `P`. | One character. | | `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. | | | `PAYMENTNUM` | Payment number identifying the failed payment to be retried. | Numeric. | | `AMT` | If specified, overwrites the original payment amount for this payment only. This value does not modify the `AMT` specified in the profile. This parameter is useful for catching up on failed past payments. Not required if retrying for the original amount. | Numeric; ten characters including the decimal point. | ### Returned Values for the Payment Action [#returned-values-for-the-payment-action] The following table describes the return values for a profile with no Optional transaction. | Field | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `RESULT` | Result value for the action. | | `RPREF` | Reference number to this particular action request. | | `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. | ### Returned Values if You Specify an Optional Transaction [#returned-values-if-you-specify-an-optional-transaction-2] The following table 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). | Field | Description | | ------------ | -------------------------------------- | | `TRXPNREF` | `PNREF` of the optional transaction. | | `TRXRESULT` | `RESULT` of the optional transaction. | | `TRXRESPMSG` | `RESPMSG` of the optional transaction. | ## Testing Recurring Billing [#testing-recurring-billing] This section provides the information you need to test recurring billing. In this section: * [Testing Guidelines](#testing-guidelines) * [Credit Card Numbers Used for Testing](#credit-card-numbers-used-for-testing) * [Testing Result Value Responses](#testing-result-value-responses) ### Testing Guidelines [#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). * Use [PayPal Manager](https://manager.paypal.com) to view the credit card processor that you have selected for testing. ### Credit Card Numbers Used for Testing [#credit-card-numbers-used-for-testing] Use the following card numbers for testing. Any other card number produces a general failure. Test credit card numbers | Field | Description | | -------------------------- | ---------------- | | American Express | 378282246310005 | | American Express | 371449635398431 | | American Express Corporate | 378734493671000 | | Diners Club | 30569309025904 | | Diners Club | 38520000023237 | | Discover | 6011111111111117 | | Discover | 6011000990139424 | | JCB | 3530111333300000 | | JCB | 3566002020360505 | | Mastercard | 5555555555554444 | | Mastercard | 5105105105105100 | | Visa | 4111111111111111 | | Visa | 4012888888881881 | | Visa | 4222222222222 | > **Note:** **Note:** 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 [#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. | Amount | RESULT (RESPMSG) | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | $0 – $1000 | RESULT value 0 (Approved) | | $1001 – $2000 | Certain amounts in this range return specific PayPal results, and can be generated by adding $1000 to that RESULT value. For example, for RESULT value 13 (Referral), submit the amount 1013. If the amount is in this range but does not correspond to a PayPal result supported by this testing mechanism, RESULT value 12 (Declined) is returned. | | $2001+ | RESULT value 12 (Declined) | ## Obtaining Consent to Bill Customers Using Recurring Billing [#obtaining-consent-to-bill-customers-using-recurring-billing] You must get 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. Merchant hereby represents and warrants that Merchant has the authorization to bill its customers' credit card accounts in the manner, for the amounts and for the period of time indicated by Merchant at the time Merchant enrolls with PayPal. * Complying with all applicable bank and credit card rules with respect to recurring billing of consumers' credit cards. Merchant hereby represents and warrants that Merchant has complied with all applicable bank and credit card rules in billing its customers' credit card and in its use of PayPal Merchant Services. * Providing accurate information regarding the credit cards to be billed, the amounts, the billing cycles, billing period and any other information requested by PayPal that is necessary to properly process such Transactions.