How to Create a Recurring Payments Profile with Express Checkout
To create a recurring payments profile with Express Checkout:
- Setting up the payment authorization.
- Redirecting the customer to PayPal for authorization.
- Obtaining customer details.
- Creating the recurring payments profile.
- 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
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:
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.
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
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).
CreateRecurringPaymentsProfile request below includes fields for the recurring payments profile:
PROFILESTARTDATE: The start date of billing.
DESC: The same description as you used in
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:
- Log into the Sandbox.
- Click Test Accounts.
- Under Log-in Email, select the test user who authorized the recurring payments profile.
- Click Enter Sandbox Test Site.
- In the new window, log in with the test user.
- 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.