Create a Recurring Payments Profile with Express Checkout

Important: This integration method is Deprecated as of January 1, 2017. For new integrations, see the PayPal Express Checkout Integration Guide.

To create a recurring payments profile with Express Checkout:

  1. Set up the payment authorization.
  2. Redirect the customer to PayPal for authorization.
  3. Obtain customer details.
  4. Create the recurring payments profile.
  5. Optionally, review the recurring payments profile.

Note: For information about how recurring payments work, see Handling Recurring Payments.

Set up the payment authorization

When a customer is ready to check out, set the L_BILLINGTYPE0=RecurringPayments and provide a billing agreement description in the SetExpressCheckout call.

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=https://example.com/cancel    #For use if the consumer decides not to proceed with payment
&returnUrl=https://example.com/success   #For use if the consumer proceeds with payment

Response

The SetExpressCheckout response returns a token that you use in subsequent calls. For parameter descriptions, see the SetExpressCheckout API Operation.

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

Redirect the customer to PayPal for authorization

Use the token returned from SetExpressCheckout to redirect the customer to PayPal.

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

If the customer does not authorize the billing agreement, restart the checkout by redirecting the customer to the cancel URL that you specified in the SetExpressCheckout call.

Obtain customer details

If the customer authorizes the payment, redirect the customer to the return URL that you specified in the SetExpressCheckout call and append the token to the return URL.

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

This sample code includes the URL-decoded token.

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

Create the recurring payments profile

To create the recurring payments profile, specify the URL-decoded token and PayerID in the CreateRecurringPaymentsProfile call.

Request

This request creates a profile that charges the customer $10 per month for a fitness membership. The request includes these fields for the recurring payments profile:

PROFILESTARTDATE The billing start date.
DESC The description, which is the same description that you defined in the SetExpressCheckout call.
BILLINGPERIOD The time period between billings.
BILLINGFREQUENCY The frequency of charges.
AMT The amount the customer will pay in a payment period.
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

The response contains an ActiveProfile status, indicating that the customer will be billed, and a PROFILEID value. Save the PROFILEID value to manage the recurring payments profile.

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

For field descriptions and other options, including a trial period and setup fee, see the CreateRecurringPaymentsProfile API Operation.

Review the recurring payments profile

Optionally, you can modify a recurring payments profile with the UpdateRecurringPaymentsProfile call.

These steps describe how to review the profile in the PayPal sandbox:

  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. Under the My Recent Activity table, find a row with Recurring Payment To in the Type column. To view information about the recurring payments profile, click Details.

Additional information