Website Payments Pro Recurring Payments

You can set up a recurring payment to handle a subscription, billing agreement, or other payment that occurs on a fixed schedule. Recurring payments support debit or credit cards.

Integration steps

Get purchase information from the buyer

To set up a recurring payment for a buyer, get the required information from the buyer, including the billing amount and the buyer's credit card information. Then create a recurring payments profile with the required information.

PayPal automatically queues recurring payments based on the billing start date, billing frequency, and billing amount.

Payments continue until one of these conditions occur:

• You cancel the profile.
• The profile expires.
• The number of failed payments exceeds the maximum number of allowed failed payments.

Activity reports for recurring payments (subscriptions) are available in the paypal.com Activity and Reports pages.

Create a recurring payments profile

To create a recurring payment profile, call CreateRecurringPaymentsProfile API operation (NVP, SOAP). Include all required credit card data in the CreateRecurringPaymentsProfile request. Do not include a value in the TOKEN field.

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

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

As with all direct payments, PayPal is completely invisible to your buyer throughout 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.

To learn more about recurring payments advanced integration features, see recurring payments additional features.

Sample: creating a recurring payments profile

The following sample code demonstrates how to create a recurring payments profile, including the credit card number, the billing address, and the payment amount. The request charges the customer $10 a month for a racquetball club membership.

The following minimum required information is required:

• Profile start date — The start date of billing.
• Description — The description of the profile.
• Billing period — Time period between billings, such as monthly.
• Billing frequency — Frequency of charges. This is a numeric value and for once per month is set to 1.
• Amount — The amount the buyer will pay in a payment period, such as 10.00.

Request

1Endpoint URL: https://api-3t.sandbox.paypal.com/nvp
2HTTP method: POST
3POST data:
4USER=insert_merchant_user_name_here
5&PWD=insert_merchant_password_here
6&SIGNATURE=insert_merchant_signature_value_here
7&METHOD=CreateRecurringPaymentsProfile
8&PROFILESTARTDATE=2012-05-11T00:00:00Z    #Billing date start, in UTC/GMT format
9&DESC=RacquetClubMembership    #Profile description - same value as a billing agreement description
10&BILLINGPERIOD=Month    #Period of time between billings
11&BILLINGFREQUENCY=1    #Frequency of charges
12&AMT=10    #The amount the buyer will pay in a payment period
13&MAXFAILEDPAYMENTS=3    #Maximum failed payments before suspension of the profile
14&ACCT=4641631486853053    #The credit card number
15&CREDITCARDTYPE=VISA    #The type of credit card
16&CVV2=123    #The CVV2 number
17&FIRSTNAME=James
18&LASTNAME=Smith
19&STREET=FirstStreet
20&CITY=SanJose
21&STATE=CA
22&ZIP=95131
23&COUNTRYCODE=US    #The country code, e.g. US
24&CURRENCYCODE=USD    #The currency, e.g. US dollars
25&EXPDATE=052015     #Expiration date of the credit card

Response

1PROFILEID=I%2dWMA886VL1234
2&PROFILESTATUS=ActiveProfile
3&ACK=Success
4...

The call response contains an ActiveProfile status, indicating that the customer will be billed, and a PROFILEID value. Save the PROFILEID value for use later in managing the recurring payments profile.

For field descriptions and other options for recurring payments, see the CreateRecurringPaymentsProfile (NVP, SOAP) reference pages. For information about notifications, see Instant Payment Notification.

Review the recurring payments profile

You can optionally review your recurring payments profile. Because you created the profile in the PayPal sandbox environment, the following steps are for the PayPal sandbox site.

1. Log in to the PayPal sandbox as the test merchant account that will receive the recurring payments.
2. Under View Transactions, click All Account Activity.
3. In the most recent recurring payment row in the All Activity table, click Details.
4. Review the details of the profile, which include the profile ID, next payment date, amount due per cycle, and other information.

Handle declined payments

Some card issuers send a one- to two-digit payment advice code in the PaymentAdviceCode response field of a declined payment transaction.

Both Visa and Mastercard issuers send payment advice codes. As a merchant, you must capture these codes to determine why the payment was declined. For example, the card might be expired or terminated, the account has insufficient funds, or the buyer wants to cancel a recurring payment.

The following is an example of a transaction response containing a payment advice code:

1PAYMENTADVICECODE=3&TIMESTAMP=2011%2d06%2d01T23%3a43%3a25Z&CORRELATIONID=bf130fe2af88b&ACK=Failure&VERSION=76%2e0&BUILD=1919055&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Invalid%20Data&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&L_SEVERITYCODE0=Error&AMT=1%2e00&CURRENCYCODE=USD

See payment advice codes on the response codes reference page.

(Optional) Prepare for 3-D Secure

PayPal will implement 3-D Secure authentication for recurring payments in September 2019, and you can use the information in this section to plan for your 3-D Secure 2.0 integration updates.

For UK merchants, Strong Customer Authentication (SCA), a requirement of the second Payment Services Directive (PSD2), goes into effect on September 14, 2019. With SCA, cardholder-initiated transactions will require two forms of authentication in order to be processed. The following actions for recurring payments are considered cardholder-initiated and require the transaction to be authenticated using SCA:

• Creating a recurring payment profile
• Updating a recurring payment profile

Transactions that occur outside of those two actions, like regularly scheduled subscription payments, are merchant-initiated transactions and don't require additional authentication through SCA.

The steps for creating or updating a payment profile with SCA are generally the same as they have been, with the addition of an authentication step and a new error code that PayPal returns for SCA-related transaction failures:

• Creating a recurring payment profile by calling CreateRecurringPaymentsProfile to provide transactional information and 3-D Secure authentication data returned in the previous step.

  If the transaction succeeds, CreateRecurringPaymentsProfile returns a Profile ID you can use for updating the profile in the future. Also, the buyer is charged the subscription amount on the start date for the frequency and duration indicated in the profile.

• Updating a recurring payment profile by calling UpdateRecurringPaymentsProfile to provide the new card information, the existing Profile ID for the customer (returned by the original CreateRecurringPaymentsProfile call), and the 3-D Secure authentication data returned in the previous step.

  If the update succeeds, UpdateRecurringPaymentsProfile returns the same Profile ID you passed.

3-D Secure guidance for specific recurring payment scenarios

PayPal provides the following guidance for 3-D Secure authentication in these specific recurring payment scenarios:

Additional fields for CreateRecurringPaymentsProfile and UpdateRecurringPaymentsProfile

When PayPal implements 3-D Secure authentication for recurring payments, the following 3-D Secure fields will be added to CreateRecurringPaymentsProfile and UpdateRecurringPaymentsProfile.

Recurring Payments additional features

For information about recurring payments API operations, see the Recurring Payments section of the Website Payments Pro API reference. This list briefly describes these features:

• Include an optional trial period.
• Specify an initial payment.
• Set the maximum number of failed payments.
• Specify whether PayPal should add any failed payments to the outstanding amount of the next billing cycle. You can also immediately bill the outstanding amount of a profile.
• Determine the recurring payments profile status.
• Obtain information about a recurring payment profile.
• Modify a recurring payments profile. This includes updating the buyer's address or the amount of the recurring payment.

Additional information

• PayPal recurring payments terminology

Next

Learn about reference transactions.