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:
- Apps 101 — For API credentials and endpoints.
- Express Checkout Introduction
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.
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=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:
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.
If the customer provides authorization, the customer is redirected to the return URL that you specified in the SetExpressCheckout call.
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.
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=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
The 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.
The 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.
In the 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)
After you use the CreateRecurringPaymentsProfile call, you can modify the profile, e.g. the subscription price, with the UpdateRecurringPaymentsProfile call. Also see Handling Recurring Payments.
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.
