How to Use Express Checkout to Offer a Subscription with a Free Trial
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.
In Express Checkout, offering a subscription with a free trial requires:
- Setting up the subscription plan.
- Redirecting the customer to PayPal for authorization.
- Obtaining customer details.
- Including a free trial in a recurring payments profile.
- Optionally, reviewing the free trial information in the recurring payments profile.
For background information, see:
For information about how to create a profile without a free trial, see How to Create a Recurring Payments Profile with Express Checkout.
Note: Below are samples that contain parameters for POST requests.
Step 1: Set Up the Subscription Plan
When a customer is ready for authorization, 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=PhotoStorage. In Step 4, you provide additional information about the subscription plan.
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=94 &L_BILLINGTYPE0=RecurringPayments #The type of billing agreement &L_BILLINGAGREEMENTDESCRIPTION0=PhotoStorage #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 -------- 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.
If the customer provides authorization, the customer is redirected to the return URL that you specified in the
Step 3: Obtain Customer Details
As described in Step 2, if the customer provides authorization, 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=94 &TOKEN=insert_token_value_here Response -------- TOKEN=token_value &BILLINGAGREEMENTACCEPTEDSTATUS=1 &ACK=Success &PAYERID=3TXTXECKF1234 ...
Step 4: Include a Free Trial in a Recurring Payments Profile
CreateRecurringPaymentsProfile call below creates and activates a profile, with a one-month free trial, for a photo storage service. After the free trial, the customer is billed one dollar per month. In a profile for a different product, you could specify a billing amount for the trial period, or simply use the free trial period shown below.
After the trial period ends, the customer will be billed under the regular payment terms, unless the customer cancels the recurring payment profile.
You can call
ManageRecurringPaymentsProfileStatus to cancel the profile; see Handling Recurring Payments.
CreateRecurringPaymentsProfile request below includes fields for a trial period:
TRIALBILLINGPERIOD: Period of time in one trial period. For example, a month.
TRIALBILLINGFREQUENCY: Frequency of charges, if any, in a period.
TRIALTOTALBILLINGCYCLES: Trial period's length. That is, the number of periods in the trial.
TRIALAMT: Payment amount during the trial period. For example, zero.
The call response contains an
ActiveProfile status, indicating that the profile is in effect, 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 API Operation.
CreateRecurringPaymentsProfile call, use the URL-decoded token (see above), along with the
PayerID from the
GetExpressCheckoutDetails call (Step 3).
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=94 &TOKEN=insert_token_value_here &PAYERID=payer_id_value #Identifies the customer's account &PROFILESTARTDATE=2012-09-12T00:00:00Z #Billing date start, in UTC/GMT format &DESC=PhotoStorage #Profile description - same as billing agreement description &BILLINGPERIOD=Month #Period of time between billings &BILLINGFREQUENCY=1 #Frequency of charges &AMT=1 #The amount the buyer will pay in a payment period &TRIALBILLINGPERIOD=Month #Period of time in one trial period &TRIALBILLINGFREQUENCY=1 #Frequency of charges, if any, during the trial period &TRIALTOTALBILLINGCYCLES=1 #Length of trial period &TRIALAMT=0 #Payment amount (can be 0) during the trial 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: Update the Profile (Optional)
You also can review information about the profile, including the trial period, in the PayPal sandbox as follows:
- 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.
- 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, including the trial period.