PayPal Recurring Payments allows you to bill a buyer for a fixed amount of money on a fixed schedule. The buyer signs up for recurring payments during checkout from your site. Consider the following examples:
When you create recurring payments for a buyer, you create a recurring payments profile. The profile contains information about the recurring payments, including details for an optional trial period and a regular payment period. Each of these subscription periods contains information about the payment frequency and payment amounts, including shipping and tax, if applicable.
After a profile is created, PayPal automatically queues payments based on the billing start date, billing frequency, and billing amount, until the profile expires or is canceled by the merchant. The buyer can also cancel the recurring payment profile.
After the recurring payments profile is created, you can view recurring payments details or cancel the recurring payments profile from your PayPal account.You can also access recurring payments reports from the PayPal
Business Overview page.
Table 4.1 lists commonly used terms related to recurring payments.
|
|
|
|
|
|
Calls SetExpressCheckout with one or more billing agreement details in the request
|
|
|
|
|
|
|
|
https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout
&token= <token returned by SetExpressCheckout>
|
|
|
|
|
|
|
|
|
Redirects buyer’s browser to returnURL passed to SetExpressCheckout if buyer agrees to payment description.
|
|
|
Calls GetExpressCheckoutDetails to get buyer information (optional).
|
|
|
|
|
Returns GetExpressCheckoutDetails response.
|
|
|
|
|
|
|
Calls DoExpressCheckoutPayment if the order includes one-time purchases as well as a recurring payment. Otherwise, skip this step.
|
|
|
|
|
Returns DoExpressCheckoutPayment response
|
|
|
Calls CreateRecurringPaymentsProfile one time for each recurring payment item included in the order.
|
|
|
|
|
Returns ProfileID in CreateRecurringPaymentsProfile response for each profile successfully created.
|
|
|
|
|
As in the Express Checkout flow, the SetExpressCheckout request notifies PayPal that you are initiating an order that can be either a one-time purchase, up to ten recurring payments, or a mixture of a one-time purchase and recurring payments.
To include one or more recurring payments in the SetExpressCheckout request, you must set the following fields:
The SetExpressCheckout response provides a token that uniquely identifies the transaction for subsequent redirects and API calls.
After you receive a successful response from SetExpressCheckout, add the
TOKEN from the
SetExpressCheckout response as a name/value pair to the following URL, and redirect your buyer’s browser to it:
For redirecting the buyer’s browser to the PayPal login page, PayPal recommends that you use the HTTPS response 302 “Object Moved” with the URL above as the value of the
Location header in the HTTPS response. Ensure that you use an SSL-enabled server to prevent browser warnings about a mix of secure and insecure graphics.
The GetExpressCheckoutDetails method returns information about the buyer, including name and email address stored on PayPal. You can optionally call this API after PayPal redirects the buyer’s browser to the
ReturnURL you specified in the
SetExpressCheckout request.
The GetExpressCheckoutDetails request has one required parameter,
TOKEN, which is the value returned in the
SetExpressCheckout response.
After your buyer has agreed to the recurring payments billing agreement on your confirmation page, you must call
CreateRecurringPaymentsProfile to create the profile. If you are creating multiple recurring payments profiles, you must call
CreateRecurringPaymentsProfile once for each profile to be created.
If the transaction includes a mixture of a one-time purchase and recurring payments profiles, call
DoExpressCheckoutPayment to complete the one-time purchase transaction, and then call
CreateRecurringPaymentsProfile for each recurring payment profile to be created.
The CreateRecurringPaymentsProfile response contains a Profile ID, which is an encoded string that uniquely identifies the recurring payments profile.
You can optionally include a value for TOTALBILLINGCYCLES (SOAP field
ScheduleDetails.PaymentPeriod.TotalBillingCycles), which specifies the total number of billing cycles in the regular payment period. If no value is specified or if the value is 0, the payments continue until the profile is canceled or suspended. If the value is greater than 0, the regular payment period will continue for the specified number of billing cycles.
You can optionally specify an initial non-recurring payment when the recurring payments profile is created by including the following fields in the
CreateRecurringPaymentsProfile request:
By default, PayPal will not activate the profile if the initial payment amount fails. You can override this default behavior by setting the
FAILEDINITAMTACTION field to
ContinueOnFailure, which indicates that if the initial payment amount fails, PayPal should add the failed payment amount to the outstanding balance due on this recurring payment profile.
If this field is not set or is set to CancelOnFailure, PayPal will create the recurring payment profile, but will place it into a pending status until the initial payment is completed. If the initial payment clears, PayPal will notify you by IPN that the pending profile has been activated. If the payment fails, PayPal will notify you by IPN that the pending profile has been canceled.
By including the MAXFAILEDPAYMENTS field in the
CreateRecurringPaymentsProfile request, you set the number of failed payments allowed before the profile is automatically suspended. You receive an IPN message when the number of failed payments reaches the maximum number specified.
If a payment fails due to any reason, the amount that was to be billed (including shipping and tax, if applicable) is added to the profile’s outstanding balance. Use the
AUTOBILLOUTAMT field in the
CreateRecurringPaymentsProfile request to specify whether or not the outstanding amount should be added to the payment amount for the next billing cycle.
If the profile is successfully created, it has an ActiveProfile status. However, as described in
“Specifying an Initial Payment”, if a non-recurring initial payment fails and
FAILEDINITAMTACTION is set to
CancelOnFailure in the
CreateRecurringPaymentsProfile request, the profile is created with a status of
PendingProfile until the initial payment either completes successfully or fails.
A profile has a status of ExpiredProfile when both the total billing cycles for both the optional trial period and the regular payment period have been completed.
You can suspend or cancel a profile by using the ManageRecurringPaymentsProfileStatus API. You can also reactivate a suspended profile.
Use the GetRecurringPaymentsProfileDetails API to get information about a profile. Along with the information that you specified in the
CreateRecurringPaymentsProfile request,
GetRecurringPaymentsProfileDetails also returns the following summary information about the profile:
Use the UpdateRecurringPaymentsProfile API to modify a recurring payments profile.
For complete details, see the Name-Value Pair Developer Guide and Reference or the
SOAP API Reference.
For example, if you want to update the subscriber’s street address, you must specify all of the address fields listed in the
Name-Value Pair Developer Guide and Reference or
SOAP API Reference, not just the field for the street address.
For profiles created using Express Checkout, the total amount of a recurring payment can only be increased 20% in a fixed 180-day interval after the profile is created. The 20% maximum is based on the total amount of the profile at the beginning of the 180-day interval, including any shipping or tax amount.
For example, if a profile is created on March 10 with a total amount of $100, then during the 180-day interval from March 10 to September 6, you can increase the payment amount to a maximum of $120 (120% of $100).
Suppose that during the first 180-day interval, you increased the payment amount to $110. Then during the next 180-day interval (starting on September 7 in this example), you can only increase the amount of the payment to a maximum of $132 (120% of $110).
Use the BillOutstandingAmount API to immediately bill the buyer for the current past due or outstanding amount for a recurring payments profile. To bill the outstanding amount:
|
l
|
The BillOutstandingAmount call cannot be within 24 hours of a regularly scheduled payment for this profile.
|
You will be informed by IPN about the success or failure of the outstanding payment. For profiles created using Express Checkout, the buyer will receive an email notification of the payment.
Merchants are notified of certain events through IPN. For recurring payments profiles created using Express Checkout, buyers are also notified of specific events by email.
Table 4.7 indicates when IPN or emails are generated.
|
Note:
|
API transactions such as ManangeRecurringPaymentsProfileStatus do not trigger IPN notification because the success or failure of the call is immediately provided by the API response.
|
