Recurring Payments

The Recurring payments module shows recurring payment information to the buyer before they commit to the payment.

Eligibility

• Available for buyers and merchants in the United States.
• Must be integrated using the Payment Method Tokens v3 API for a Save for Purchase Later buyer experience.
• JavaScript SDK and API support only client-side integration.

How it works

1. The buyer signs up for your service and adds PayPal as a payment method.
2. PayPal authenticates the buyer and creates a setup token.
3. The Recurring Payments module shows the buyer details about the recurring payment.
4. The buyer consents to the billing agreement.
5. PayPal creates a payment token that you can use to create and capture payments.

1. Recurring payments flow

Step 1. Create setup token

To set up the recurring payment module, pass additional fields in the Create setup token request. The buyer reviews and agrees to the recurring billing terms to allow the merchant to charge their PayPal account for future payments.

There are two types of information that you need to provide:

Recurring payment type

Pass the recurring payment type in the payment_source.paypal.usage_pattern field of the Create setup token request when you set the payment method. This flags the payment method token for future recurring payments and tailors content in the PayPal flow to show the buyer that this will be a recurring payment.

Recurring payment options include subscriptions, unscheduled payments, and installments. Choose prepaid when the payments are upfront or postpaid when the payments come after the goods or services are delivered.

Recurring billing plan

This shows the buyer a summary of the recurring payment agreement in PayPal. The recurring billing plan details are passed in the payment_source.paypal.billing_plan object of the Create setup token request:

• name: The billing plan name is an optional description used to provide further information to the buyer about the service they are purchasing as part of a recurring payment arrangement. This is displayed within the PayPal flow.
• billing_cycles: The billing cycle is a set of attributes relating to the amount and duration of a billing agreement. Although most recurring payments consist of only one or two billing cycles, PayPal’s recurring payments structure supports an array of up to 3 billing cycles to support more complex recurring payment arrangements. A billing cycle may either be a trial or a regular cycle. Trial cycles may be either chargeable or free.
• one_time_charges: Data that can be provided for a one-time fee that is not part of the ongoing recurring payment arrangement with the payer. Examples of this include setup fees and items ordered when establishing a recurring payment, such as a mobile phone purchased upon signing up for a service plan.
  

Step 2. Get buyer approval

Get the buyer’s approval for a recurring payment plan by sending a POST request to the Authorize payment for order endpoint of the Create Orders v2 API.

By default, the setup token expires after 3 days.

Step 3. Ceate payment token

After the payer completes the approval flow, you can upgrade the setup token to a full payment method token by sending a POST call to the Create payment token for a given payment source endpoint of the Payment Method Tokens v3 API. The endpoint returns the payment source details, links, payment token ID, and customer details.

1. Use token as the payment_source and complete the rest of the source objects for your use case and business.
2. Pass your setup token ID in the payment_source parameter and set the type as SETUP_TOKEN.

Store the merchant payer ID aligned with your system to simplify the mapping of payer information between your system and PayPal. This is an optional field that returns the value shared in the response.

Step 4. Use payment method token with checkout

After you create a payment method token, use the token instead of the payment method to create a purchase and capture the payment with the Create orders endpoint of the Orders v2 API. Use this to charge your buyers for their recurring payments.

1. Use the ID of your payment method token as the vault_id.
2. Specify intent to indicate whether to capture a payment immediately or authorize it for a payment later. Use AUTHORIZE for Auth-Capture.
3. Add amount for the total order.
4. Update stored_credential as the payment source for a vaulted payment method token to provide additional details for recurring transactions that include usage_pattern, payment_initiator, and usage.

2. Customize your plan

Configure your usage_pattern and billing_cycle to match your needs. For more information on billing cycle customizations see the Create a setup token endpoint of the Payment Method Tokens v3 API.

1. Use paypal as the payment_source. Pass additional parameters in the paypal object for your use case and business.
2. Pass the usage_pattern and billing_plan details using the payment_source.paypal object. These are the details that the payer sees on the PayPal review page.
3. Update the return_url value with the URL where the payer is redirected after they approve the flow.
4. Update the cancel_url value with the URL where the payer is redirected after they cancel the flow.

By default, the setup token expires after 3 days. After the payer completes the approval flow, you can upgrade the setup token to a full payment method token by calling the Create payment token for a given payment source endpoint of the Payment Method Tokens v3 API.