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.

Note: If you offer free-trial periods or recurring subscription payments, you can use card verifications to verify a buyer's card before you create a recurring payment.

Integration steps

1. Required Get purchase information from the buyer.
2. Required Create a recurring payments profile.
3. Optional Review the recurring payments profile.
4. Optional Handle declined payments.
5. Optional Review recurring payments additional features.

Get purchase information from the buyer

To set up a recurring payment for a buyer, you must obtain all of the necessary information from the buyer, including the billing amount and 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 reoccur until on the of the following conditions takes place:

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

Note: You can view profile details or cancel the profile from your paypal.com account. The buyer can also cancel a recurring payments profile; see handle declined payments for more information.

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 information 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.

NVP SOAP
CREDITCARDTYPE CreditCardDetails.CreditCardType
ACCT CreditCardDetails.CreditCardNumber
EXPDATE CreditCardDetails.ExpMonth and CreditCardDetails.ExpYear
FIRSTNAME code>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.

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.

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

Create the recurring payment profile

First, create the recurring payments profile. The payment data includes the credit number in the account field, along with the billing address and payment amount.

Request

This request charges the customer $10 a month for a racquetball club membership.

The following is the minimum required information:

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

Response

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

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 test 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:

PAYMENTADVICECODE=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.

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:

Additional information

Next

Learn about reference transactions.