Create a Recurring Payments Profile with Express Checkout
Important: This integration method is deprecated as of January 1, 2017. PayPal continues to support existing merchants using this method, but please be advised new features and enhancements will not be applied to these integrations. For new integrations, see the PayPal Checkout Integration Guide.
To create a recurring payments profile with Express Checkout:
- Set up the payment authorization.
- Redirect the customer to PayPal for authorization.
- Obtain customer details.
- Create the recurring payments profile.
- 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:
- Log into the sandbox.
- Click sandbox accounts.
- Under Log-in Email, select the test user who authorized the recurring payments profile.
- Click Enter Sandbox Test Site.
- 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.
