Integrating Recurring Payments

How Recurring Payments Work

To view a video that demonstrates how to set up Recurring Payments, navigate to: Recurring Payments Demo

When you support recurring payments for a buyer, you create a recurring payments profile. The profile contains information about the recurring payments, including details for an optional trial period and a regular payment period. Both periods contain information about the payment frequency and payment amounts, including shipping and tax, if applicable.

After creating a profile, PayPal automatically queues payments based on the billing start date, billing frequency, and billing amount. Payments reoccur until the profile expires, there are too many failed payments to continue, or you cancel the profile.

Note: When using Express Checkout, the buyer can also cancel a recurring payments profile.

PayPal funds queued payments using the normal payment method hierarchy within the buyer's PayPal account.

After creating a recurring payments profile, you can view profile details or cancel the profile from your PayPal account. You can also access recurring payments reports from the PayPal Business Overview page.

Also, after creating a recurring payments profile, you can use the Recurring Payments API to do the following:

  • Get information details about a recurring payments profile.
  • Change the status of a recurring payments profile.
  • Update the details of the recurring payments profile.
  • Bill the outstanding amount of the recurring payments profile.

Limitations

The current release of the Recurring Payments API has the following limitations:

  • A profile can have at most one optional trial period and a single regular payment period.
  • The profile start date may not be earlier than the profile creation date.

Recurring Payments with Express Checkout also has the following limitations:

  • To be able to create a recurring payments profile for the buyer, you must ensure that the buyer's PayPal account includes an active credit card.
  • You can create a maximum of 10 recurring payments profiles during checkout.
  • You can increase the profile amount by only 20% in each 180-day interval after you create the profile.

Recurring Payments Terms

The following table lists and describes terms that are commonly used in the context of PayPal recurring payments.

Table 1. Recurring Payments Terms

Term

Definition

Recurring payments profile Your record of a recurring transaction for a single buyer. The profile includes all information required to automatically bill the buyer a fixed amount of money at a fixed interval.
Billing cycle Make one payment per billing cycle. Each billing cycle has 2 components:
  • The billing period specifies the unit to calculate the billing cycle (such as days or months).
  • The billing frequency specifies the number of billing periods that make up the billing cycle.

For example, if the billing period is Month and the billing frequency is 2, the billing cycle is 2 months. If the billing period is Week and the billing frequency is 6, PayPal schedules the payments every 6 weeks.

Regular payment period The main subscription period for this profile, which defines a payment amount for each billing cycle. The regular payment period begins after the trial period, if you specify a trial period for the profile.
Trial period An optional subscription period before the regular payment period begins. A trial period may not have the same billing cycles and payment amounts as the regular payment period.
Payment amount The amount the buyer pays for each billing cycle.
Outstanding balance If a payment fails for any reason, PayPal adds that amount to the profile's outstanding balance.
Profile ID An alphanumeric string (generated by PayPal) that uniquely identifies a recurring profile. You can specify the Profile ID in the TransactionSearch API operation to obtain all payments associated with the identified profile.

Recurring Payments With Direct Payment

Recurring payments with Direct Payment enables a recurring payment to be associated with a debit or credit card. For these payments, you must collect on your website all necessary information from your buyer, including billing amount and buyer's credit card information.

Merchants who offer free trial periods or plan to bill the first installment of a recurring payment at a later date may find it worthwhile to use the card verification feature. This feature allows merchants to verify the buyer's card, as a potential loss mitigation tool, prior to extending the service. Also, merchants can verify the buyer's card before saving the card information and creating the buyer's recurring payment profile.

After you have collected the information, call the CreateRecurringPaymentsProfile API for each profile to be created. The CreateRecurringPaymentsProfile request must contain all required credit card information and must not contain a value for the TOKEN field.

The following table lists the fields that are required in the CreateRecurringPaymentsProfile request for recurring payments using direct payments.

Table 2. Required fields for CreateRecurringPaymentsProfile in Direct Payment

NVP

SOAP

CREDITCARDTYPE CreditCardDetails.CreditCardType
ACCT CreditCardDetails.CreditCardNumber
EXPDATE CreditCardDetails.ExpMonth and CreditCardDetails.ExpYear
FIRSTNAME CreditCardDetails.CardOwner.PayerName.FirstName
LASTNAME CreditCardDetails.CardOwner.PayerName.LastName
PROFILESTARTDATE RecurringPaymentProfileDetails.BillingStartDate
BILLINGPERIOD ScheduleDetails.PaymentPeriod.BillingPeriod
BILLINGFREQUENCY ScheduleDetails.PaymentPeriod.BillingFrequency
AMT ScheduleDetails.PaymentsPeriod.Amount

The CreateRecurringPaymentsProfile response contains a Profile ID, which is an encoded string that uniquely identifies the recurring payments profile.

For more options when creating a recurring payments profile, see Options for Creating a Recurring Payments Profile.

As with all direct payments, PayPal is completely invisible to your buyer before, during, and after the purchase. PayPal does not send an email receipt to the buyer, nor will the buyer's credit card statement indicate that PayPal processed the payment.

Recurring Payments With the Express Checkout API

During the checkout flow, you can create one or more recurring payments and mix recurring payments with other purchases.

The following diagram illustrates the typical processing flow to create recurring payments during checkout.



The circled numbers in the diagram correspond to the numbered steps in the following table:

Table 3. Recurring payments processing flow

Step

Merchant...

PayPal...

1 Calls SetExpressCheckout, setting up one or more billing agreements in the request.

2

Returns a token, which identifies the transaction, to the merchant.
3 Redirects buyer's browser to:

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout &token=<token returned by SetExpressCheckout>

Displays login page and allows buyer to select payment options and shipping address.
4

Redirects buyer's browser to returnURL passed to SetExpressCheckout if buyer agrees to payment description.
5 Calls GetExpressCheckoutDetails to get buyer information (optional).

Returns GetExpressCheckoutDetails response.

Displays merchant review page for buyer.

6 Calls DoExpressCheckoutPayment if the order includes one-time purchases as well as a recurring payment. Otherwise, skip this step.

Returns DoExpressCheckoutPayment response

Calls CreateRecurringPaymentsProfile one time for each recurring payment item included in the order.

Returns ProfileID in CreateRecurringPaymentsProfile response for each profile successfully created.
7 Displays successful transaction page.

Initiating the Processing Flow With SetExpressCheckout

As in the Express Checkout flow, the SetExpressCheckout request notifies PayPal that you are:

  • Initiating an order that can be either a one-time purchase, up to 10 recurring payments, or a mixture of a one-time purchase and recurring payments
  • Initiating the processing flow to create one or more billing agreements for recurring payments with no associated one-time purchase or recurring payment
Note: You can also initiate the processing flow using SetCustomerBillingAgreement for orders that contain only a single recurring payment.

Typically, you set the amount of the payment for an Express Checkout transaction when you call the SetExpressCheckout request. You confirm the amount in the DoExpressCheckoutPayment request. If, however, you set the amount of the payment to 0 in the SetExpressCheckout request, you can create a billing agreement without initiating a payment.

Note: To create a billing agreement without purchase, use Version 54.0 or higher, of the PayPal API.

To set up one or more billing agreements for recurring payments, modify the SetExpressCheckout request as follows:

  1. Add an L_BILLINGTYPEn field for each billing agreement you want to create; n is a value in the range of 0 to 9, inclusive. Set the value of each field to RecurringPayments.

    L_BILLINGTYPE0=RecurringPayments

  2. Add an L_BILLINGAGREEMENTDESCRIPTIONn field to correspond to each L_BILLINGTYPEn field you pass; n is a value in the range of 0 to 9, inclusive. Set the value of each field to the description of the goods or services associated with that billing agreement, for example:

    L_BILLINGAGREEMENTDESCRIPTION0=Time Magazine subscription

  3. If there is no associated purchase, set PAYMENTREQUEST_0_AMT to 0.

    PAYMENTREQUEST_0_AMT=0

  4. (Optional) Set MAXAMT to the average expected transaction amount.

    PayPal uses the value you pass to validate the buyer's payment method for recurring payments. If you do not specify a value, the default is 25.00.

The SetExpressCheckout response provides a token that uniquely identifies the transaction for subsequent redirects and API calls.

Redirecting the Buyer to PayPal

After you receive a successful response from SetExpressCheckout, add the TOKEN from the SetExpressCheckout response as a name/value pair to the following URL, and redirect your buyer to it:

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&
token=<Value-Returned-by-SetExpressCheckout>

When redirecting the buyer to PayPal, PayPal recommends that you use the HTTPS response 302 "Object Moved" with the URL as the value of the Location header in the HTTPS response. Make sure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.

Getting Buyer Details Using GetExpressCheckoutDetails

The GetExpressCheckoutDetails method returns information about the buyer, including name and email address stored on PayPal. You can optionally call this API after PayPal redirects the buyer's browser to the ReturnURL you specified in the SetExpressCheckout request.

The GetExpressCheckoutDetails request has one required parameter, TOKEN, which is the value returned in the SetExpressCheckout response.

PayPal does not return the values you specified for the following parameter fields in the GetExpressCheckoutDetails response unless the transaction includes a purchase. PayPal ignores the fields if you set up a billing agreement for a recurring payment that is not immediately charged.

  • PAYMENTREQUEST_n_DESC
  • PAYMENTREQUEST_n_CUSTOM
  • PAYMENTREQUEST_n_INVNUM

Creating the Profiles With CreateRecurringPaymentsProfile

After your buyer has agreed to the recurring payments billing agreement on your confirmation page, you must call CreateRecurringPaymentsProfile to create the profile. If you are creating multiple recurring payments profiles, you must call CreateRecurringPaymentsProfile once for each profile you plan to create.

If the transaction includes a mixture of a one-time purchase and recurring payments profiles, call DoExpressCheckoutPayment to complete the one-time purchase transaction. Then call CreateRecurringPaymentsProfile for each recurring payment profile you plan to create.

Important: PayPal does not create the recurring payments profile until you receive a success response from the CreateRecurringPaymentsProfile call.

To obtain the best rates for digital goods, set values for the following required payment details item fields:

  • L_PAYMENTREQUEST_0_NAMEn
  • L_PAYMENTREQUEST_0_AMTn
  • L_PAYMENTREQUEST_0_QTYn
  • L_PAYMENTREQUEST_0_ITEMCATEGORYn (you must set the value to Digital)
Note: The payment details item fields are available with version 69.0 and later of the CreateRecurringPaymentsProfile API.

The CreateRecurringPaymentsProfile response contains a Profile ID, which is an encoded string that uniquely identifies the recurring payments profile.

The following is a CreateRecurringPaymentsProfile example that enables you to obtain the best rates for digital goods items.

Request Parameters

[requiredSecurityParameters]
&METHOD=CreateRecurringPaymentsProfile
TOKEN=EC-13W99099UU817504D
&PROFILESTARTDATE:20XX-03-05T03:00:00
&DESC=Movie clips
&BILLINGPERIOD=Month
&BILLINGFREQUENCY=12
&AMT=1.00
&CURRENCYCODE=USD
&EMAIL=payername@bbb.net
&L_PAYMENTREQUEST_0_ITEMCATEGORY0=Digital
&L_PAYMENTREQUEST_0_NAME0=Kitty Antics
&L_PAYMENTREQUEST_0_AMT0=1.00
&L_PAYMENTREQUEST_0_QTY0=1

Response Parameters

[successResponseFields]
&PROFILEID=I-G7ALAX8095JY
&PROFILESTATUS=Active

Options for Creating a Recurring Payments Profile

You can create a recurring payments profile that allows a regular payment period, an optional trial period, an initial payment, and other options.

Specifying the Regular Payment Period

Each recurring payments profile has a regular payment period that defines the amount and frequency of the payment. The following table lists the required fields for specifying the regular payment period.

Table 4. Required fields for specifying a regular payment period

NVP

SOAP

Description

PROFILESTARTDATE RecurringPaymentsProfileDetails.BillingStartDate The date when billing for this profile begins.
Note: The profile may take up to 24 hours for activation.
BILLINGPERIOD ScheduleDetails. PaymentPeriod.BillingPeriod The unit of measure for the billing cycle. Must be one of the following:
  • Day
  • Week
  • SemiMonth
  • Month
  • Year
BILLINGFREQUENCY ScheduleDetails. PaymentPeriod.BillingFrequency The number of billing periods that make up one billing cycle. The combination of billing frequency and billing period must be less than or equal to one year.
Note: If the billing period is SemiMonth, the billing frequency must be 1.
AMT ScheduleDetails. PaymentPeriod.Amount Amount to bill for each billing cycle.

You can optionally include a value for TOTALBILLINGCYCLES (SOAP field ScheduleDetails.PaymentPeriod.TotalBillingCycles), which specifies the total number of billing cycles in the regular payment period. If you either do not specify a value or specify the value 0, the payments continue until PayPal (or the buyer) cancels or suspends the profile. If the value is greater than 0, the regular payment period continues for the specified number of billing cycles.

You can also specify an optional shipping amount or tax amount for the regular payment period.

Including an Optional Trial Period

You can optionally include a trial period in the profile by specifying the following fields in the CreateRecurringPaymentsProfile request. The following table lists the required fields for creating an optional trial period.

Table 5. Required fields for specifying a trial period

NVP

SOAP

TRIALBILLINGPERIOD ScheduleDetails.TrialPeriod.BillingPeriod
TRIALBILLINGFREQUENCY ScheduleDetails.TrialPeriod.BillingFrequency
TRIALAMT ScheduleDetails.TrialPeriod.Amount
TRIALTOTALBILLINGCYCLES ScheduleDetails.TrialPeriod.TotalBillingCycles

Specifying an Initial Payment

You can optionally specify an initial non-recurring payment when the recurring payments profile is created by including the following fields in the CreateRecurringPaymentsProfile request:

Table 6. Required fields for specifying an initial payment

NVP

SOAP

INITAMT ScheduleDetails.ActivationDetails.InitialAmount
FAILEDINITAMTACTION ScheduleDetails.ActivationDetails.FailedInitAmountAction

By default, PayPal does not activate the profile if the initial payment amount fails. To override this default behavior, set the FAILEDINITAMTACTION field to ContinueOnFailure. If the initial payment amount fails, ContinueOnFailure instructs PayPal to add the failed payment amount to the outstanding balance due on this recurring payment profile.

If you do not set FAILEDINITAMTACTION or set it to CancelOnFailure, PayPal creates the recurring payment profile. However, PayPal places the profile into a pending status until the initial payment completes. If the initial payment clears, PayPal notifies you by Instant Payment Notification (IPN) that it has activated the pending profile. If the payment fails, PayPal notifies you by IPN that it has canceled the pending profile.

If you created the profile using Express Checkout, the buyer receives an email stating that PayPal cleared the initial payment or canceled the pending profile.

Maximum Number of Failed Payments

By including the MAXFAILEDPAYMENTS field in the CreateRecurringPaymentsProfile request, you set the number of failed payments allowed before PayPal automatically suspends the profile. PayPal sends you an IPN message when the number of failed payments reaches the maximum number specified.

Billing the Outstanding Amount

If a payment fails for any reason, PayPal adds the billing amount (including shipping and tax, if applicable) to the profile's outstanding balance. Use the AUTOBILLOUTAMT field in the CreateRecurringPaymentsProfile request to specify whether PayPal should add the outstanding amount to the payment amount for the next billing cycle.

Whether or not you choose to include the outstanding amount with the payment for the next billing cycle, you can also use the BillOutstandingAmount API to programmatically collect that amount at any time.

Identifying Items as Digital or Physical Goods

Set all the payment details item fields in the following table in the CreateRecurringPaymentsProfile request. If all items are digital goods, be sure to set the item category field to Digital to get the discount rate for digital goods.

Table 7. Required fields for specifying item details

NVP

SOAP

Description

L_PAYMENTREQUEST_0_ITEMCATEGORYn ItemCategory For digital goods, this field must be set to Digital.
  • Digital
  • Physical
L_PAYMENTREQUEST_0_NAMEn Name Item name.
L_PAYMENTREQUEST_0_AMTn Amount Cost of item.
L_PAYMENTREQUEST_0_QTYn Quantity Item quantity.

Recurring Payments Profile Status

The recurring payments actions you may take depend on the status of the profile.

A recurring payments profile can have one of the following status values:

  • ActiveProfile
  • PendingProfile
  • ExpiredProfile
  • SuspendedProfile
  • CancelledProfile

If PayPal successfully creates the profile, the profile has an ActiveProfile status. However, if a non-recurring initial payment fails and you set FAILEDINITAMTACTION to CancelOnFailure in the CreateRecurringPaymentsProfile request, PayPal creates the profile with a status of PendingProfile. The profile remains in this status until the initial payment either completes successfully or fails.

A profile has a status of ExpiredProfile when PayPal completes the total billing cycles for the optional trial and the regular payment periods.

You can suspend or cancel a profile by using the ManageRecurringPaymentsProfileStatus API. You can also reactivate a suspended profile. If PayPal has already reached the maximum number of failed payments, however, you must increase the number of failed payments before reactivating the profile.

Note: You can also suspend, cancel, or reactive a recurring payments profile through the PayPal website.

For recurring payments profiles created with the Express Checkout API, the buyer receives an email about the change in status of their recurring payment.

Getting Recurring Payments Profile Information

Use the GetRecurringPaymentsProfileDetails API to obtain information about a profile.

Note: You can also get information about recurring payments profiles from the PayPal website.

Along with the information that you specified in the CreateRecurringPaymentsProfile request, GetRecurringPaymentsProfileDetails also returns the following summary information about the profile:

  • Profile status
  • Next scheduled billing date
  • Number of billing cycles completed in the active subscription period
  • Number of billing cycles remaining in the active subscription period
  • Current outstanding balance
  • Total number of failed billing cycles
  • Date of the last successful payment received
  • Amount of the last successful payment received

Modifying a Recurring Payments Profile

Use the UpdateRecurringPaymentsProfile API to modify a recurring payments profile.

Note: You can also modify recurring payments profiles from the PayPal website.

You can modify only the following specific information about an active or suspended profile:

  • Subscriber name or address
  • Past due or outstanding amount
  • Whether to bill the outstanding amount with the next billing cycle
  • Maximum number of failed payments allowed
  • Profile description and reference
  • Number of additional billing cycles
  • Billing amount, tax amount, or shipping amount
Note: You cannot modify the billing frequency or billing period of a profile. You can modify the number of billing cycles in the profile.

You can modify the following profile information during the trial period or regular payment period.

  • Billing amount
  • Number of billing cycles
Note: For recurring payments with the Express Checkout API, PayPal does not allow certain updates, such as billing amount, within 3 days of the scheduled billing date.

The profile changes take effect with the next payment after the call to update the profile. Say, for example, the buyer has made 1 trial payment out of a total of 3. You call UpdateRecurringPaymentsProfile to increase the number of billing cycles to 5. This provides the buyer with 4 additional trial payments. If you call UpdateRecurringPaymentsProfile during the regular payment period, the changes take effect with the buyer's next scheduled regular payment.

For complete details, see the Name-Value Pair Developer Guide and Reference or the SOAP API Reference.

Updating Addresses

When you update the subscriber shipping address, you must enter all of address fields, not just those that are changing:

To update the subscriber's street address, for example, specify all the address fields listed in the Name-Value Pair Developer Guide and Reference or SOAP API Reference. Do not specify only the street address field.

Updating the Billing Amount

For profiles created using Express Checkout, you can increase the recurring payment total amount by 20% maximum in a fixed 180-day interval after profile creation. The 20% maximum is based on the total amount of the profile at the beginning of the 180-day interval, including any shipping or tax amount.

If, for example, you create a profile on March 10 with a total amount of $100, during the 180-day interval from March 10 to September 6, you can increase the amount to a maximum of $120 (120% of $100).

Suppose that during the first 180-day interval, you increased the payment amount to $110. During the next 180-day interval (starting September 7), you can only increase the amount of the payment to a maximum of $132 (120% of $110).

Billing the Outstanding Amount of a Profile

Use the BillOutstandingAmount API to immediately bill the buyer for the current past due or outstanding amount for a recurring payments profile.

Note: You can also bill the buyer for the current past due or outstanding amount for a recurring payments profile from the PayPal website.

To bill the outstanding amount:

  • The profile status must be active or suspended.
    Note: The BillOutstandingAmount API does not reactivate a suspended profile. You need to call ManageRecurringProfileStatus to do this.
  • The profile must have a non-zero outstanding balance.
  • The amount of the payment cannot exceed the outstanding amount for the profile.
  • The BillOutstandingAmount call cannot be within 24 hours of a regularly scheduled payment for this profile.
Note: An error occurs when another outstanding balance payment is already queued.

PayPal informs you by IPN about the success or failure of the outstanding payment. For profiles created using Express Checkout, the buyer receives an email notification of the payment.

Recurring Payments Notifications

PayPal notifies you of recurring payments events through IPN and email. Typically, however, you can call GetTransactionDetails to obtain the information you need.

PayPal notifies you of certain events through IPN. For recurring payments profiles created using Express Checkout, PayPal also notifies buyers of specific events by email. The following table indicates when PayPal generates IPN and emails:

Table 8. Recurring payments IPN messages and email

Event

IPN

Buyer Email

Profile successfully created Yes Yes
Profile creation failed Yes Yes
Profile canceled from paypal.com interface Yes Yes
Profile status changed using API No Yes
Profile updated using API No Yes
Initial payment either succeeded or failed Yes Yes
Payment either succeeded or failed (during either trial period or regular payment period) Yes Yes
Outstanding payment either succeeded or failed Yes Yes
Maximum number of failed payments reached Yes No
Note: API transactions such as ManangeRecurringPaymentsProfileStatus do not trigger IPN notification. The API response immediately provides the success or failure of the call.