How to Create a Recurring Payments Profile with Express Checkout

To create a recurring payments profile with Express Checkout:

  1. Setting up the payment authorization.
  2. Redirecting the customer to PayPal for authorization.
  3. Obtaining customer details.
  4. Creating the recurring payments profile.
  5. Optionally, reviewing the recurring payments profile.

Tip: Review the recurring payments limitations in the Express Checkout integration guide before you get started.

For background information, see:

Note: Below are samples that contain parameters for POST requests.

Step 1: Set Up the Payment Authorization

When a customer is ready to check out, use the SetExpressCheckout call to specify recurring payments as the billing agreement type (as L_BILLINGTYPE0=RecurringPayments). Also provide a billing agreement description; for example, you could specify L_BILLINGAGREEMENTDESCRIPTION0=FitnessMembership.

The SetExpressCheckout response contains a token for use in subsequent steps. For parameter descriptions, see the SetExpressCheckout API Operation.

Request
-------
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=SetExpressCheckout
&VERSION=86
&L_BILLINGTYPE0=RecurringPayments    #The type of billing agreement
&L_BILLINGAGREEMENTDESCRIPTION0=FitnessMembership    #The description of the billing agreement
&cancelUrl=http://www.yourdomain.com/cancel.html    #For use if the consumer decides not to proceed with payment
&returnUrl=http://www.yourdomain.com/success.html   #For use if the consumer proceeds with payment

Response
--------
TOKEN=EC%2d2B984685J43051234
&ACK=Success
...

Step 2: Redirect the Customer to PayPal for Authorization

Redirect the customer to Paypal by using the token from Step 1 with the PayPal authorization URL, as follows:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=InsertTokenHere

If the customer doesn't provide authorization, the customer is redirected to the cancel URL that you specified in the SetExpressCheckout call, so you can provide a way to re-initiate checkout.

Step 3: Obtain Customer Details

If the customer authorizes the payment, the customer is redirected to the return URL that you specified in the SetExpressCheckout call. The return URL is appended with the same token as the token used above.

Make a GetExpressCheckoutDetails call to obtain a PayerID value, which uniquely identifies the customer. For parameter descriptions, see the GetExpressCheckoutDetails API Operation.

In the sample code below, insert the token string from the SetExpressCheckout response (from Step 1), after you URL-decode the token string.

Request
-------
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=GetExpressCheckoutDetails
&VERSION=86
&TOKEN=insert_token_value_here

Response
--------
TOKEN=token_value
&BILLINGAGREEMENTACCEPTEDSTATUS=1
&ACK=Success
&PAYERID=3TXTXECKF1234
...

Step 4: Create the Recurring Payments Profile

The CreateRecurringPaymentsProfile call below creates a profile that charges the customer 10 dollars per month for a fitness membership. In the CreateRecurringPaymentsProfile call, use the URL-decoded token (see above), along with the PayerID from the GetExpressCheckoutDetails call (Step 3).

The CreateRecurringPaymentsProfile request below includes fields for the recurring payments profile:

  • PROFILESTARTDATE: The start date of billing.
  • DESC: The same description as you used in SetExpressCheckout.
  • BILLINGPERIOD: Time period between billings.
  • BILLINGFREQUENCY. Frequency of charges.
  • AMT: The amount the buyer will pay in a payment period.

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, including a trial period and setup fee, see the CreateRecurringPaymentsProfile API Operation.

Request
-------
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
&VERSION=86
&TOKEN=insert_token_value_here
&PAYERID=payer_id_value   #Identifies the customer's account
&PROFILESTARTDATE=2012-05-11T00:00:00Z    #Billing date start, in UTC/GMT format
&DESC=FitnessMembership    #Profile description - same as 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
&CURRENCYCODE=USD    #The currency, e.g. US dollars
&COUNTRYCODE=US    #The country code, e.g. US
&MAXFAILEDPAYMENTS=3    #Maximum failed payments before suspension of the profile

Response
--------
PROFILEID=I%2d6D5UGCVX1234
&PROFILESTATUS=ActiveProfile
&ACK=Success
...

Step 5: Review the Recurring Payments Profile (Optional)

After you use the CreateRecurringPaymentsProfile call, you optionally can modify the profile with the UpdateRecurringPaymentsProfile call.

You also can review the profile in the PayPal Sandbox as follows:

  1. Log into the Sandbox.
  2. Click Test Accounts.
  3. Under Log-in Email, select the test user who authorized the recurring payments profile.
  4. Click Enter Sandbox Test Site.
  5. In the new window, log in with the test user.
  6. Under the My Recent Activity table, find a row with "Recurring Payment To" in the Type column. Click Details to view information about the new recurring payments profile.