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.
|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.
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
The following table lists the fields that are required in the
CreateRecurringPaymentsProfile request for recurring payments using Direct Payment.
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.
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
- Amount — The amount the buyer will pay in a payment period, such as
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
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.
- Log in to the PayPal Sandbox as the test merchant account that will receive the recurring payments.
- Under View Transactions, click All Account Activity.
- In the most recent recurring payment row in the All Activity table, click Details.
- 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:
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:
- 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.
Learn about reference transactions.