Recurring payments module
Last updated: Aug 14th, 6:43pm
Overview
The recurring payment module helps you display recurring payment information to the payer before they commit to the payment. This can increase payer conversion by building customer trust through transparency.
Pay with PayPal supports saving payment methods so that you can charge payers on a recurring basis through two integration patterns:
- Save payment methods for purchase later: Collect and store payment information for future transactions without processing an immediate payment.
- Save payment methods during purchase: Save payment details while simultaneously processing an initial transaction.
To learn more about how to save payment methods, review the Save PayPal for purchase later with the JavaScript SDK, Save PayPal with the Orders API, or Save PayPal with the Payment Method Tokens API .
Eligibility
- Available for buyers and merchants in the United States.
- To save for a purchase later, integrate using the Payment Methods Tokens v3 API.
- To save with a purchase, integrate using the Orders v2 API.
- Merchant must integrate using Save PayPal with the JavaScript SDK or have a server-side, direct-API integration with Orders API to provide the save payment method during the purchase experience.
- Merchant must integrate using Save PayPal for purchase later with the JavaScript SDK or have a server-side, direct-API integration with Payment Method Tokens API to provide the save payment method for a later purchase experience.
- JavaScript SDK and API-only server-side integrations are supported.
What are recurring payments?
Recurring payments are initiated by a merchant based on a schedule or other criteria. Examples of common recurring payments are:
- Subscriptions, such as streaming media or pet food delivery.
- Automatic bill payments, such as for utilities or mobile phone bills.
- Auto reloads, such as road tolls or prepaid cards.
Recurring payments are typically classified within the industry into one of the following types:
- Subscriptions
- Recurring
- Unscheduled account on file
- Merchant managed installments
These classifications are based on whether the amount or frequency will vary between payments and whether there is a fixed or open duration.
How it works
When a payer signs up for your service and adds PayPal as a payment method, they will go through a PayPal flow where they are authenticated and consent to a billing agreement. You can configure the PayPal flow to include a recurring payment module that shows the payer details about the billing terms on the PayPal review page.
There are two types of information that you will provide:
- Recurring payment type: This flags the payment method token for future recurring payments and tailors content in the PayPal flow to show the payer that this will be a recurring payment.
- Recurring billing plan: This shows the payer a summary of the recurring payment agreement in PayPal.
Recurring payment setup without purchase
To set up the recurring payment module to save a payment method without making a purchase, pass additional fields in the Create Setup Token and the Create Payment Token API request using the payment_source.paypal
object. When you need to charge that payment method, send a Create Order request and pass the payment token using the purchase_unit
object.
The payer reviews and agrees to the recurring billing terms to let the merchant charge their PayPal account for future payments. This is useful for free trials, postpaid services, or scenarios where the initial transaction doesn’t require immediate payment. Charges can be initiated by the merchant at a later date without requiring the customer’s presence.
For more information, see Save payment methods for purchase later.
Recurring payment setup with purchase
To set up the recurring payment module to create a payment upfront and save that payment method for future recurring payments, flag the payment method in the Create Order request. This stores the payment information for recurring purchases.
Pass the value ON_SUCCESS
in payment_source.card.attributes.vault.store_in_vault
, set MERCHANT
or CUSTOMER
in payment_source.card.attributes.vault.usage_type, and include all required metadata in the body of your Create Order request.
Recurring payment with or without purchase
Pass the recurring payment type in the appropriate usage_pattern
field when you set up the payment method. The field you use depends on whether you are saving the payment method with or without purchase.
-
With purchase: During recurring payment creation, pass the recurring payment type in the
payment_source.paypal.attributes.vault.usage_pattern
field. For subsequent payments, use thepayment_source.paypal.stored_credential.usage_pattern
field. - Without purchase: When you save the payment method without an immediate transaction, pass the recurring payment type in the
payment_source.paypal.usage_pattern
field when setting up the payment method using a Create Setup Token request. This is sent to payment networks and represents the nature of the payer’s agreement with you to ensure compliance with payment network regulations.
Refer to the usage_pattern
values column in the following table for the correct value to pass for each recurring payment type.
Recurring payments type | Amount | Billing frequency | Duration | usage_pattern values |
Subscription Represents recurring payments where the payer is charged a fixed amount on a regular basis with no specified end date. Examples include a monthly streaming media subscription or a weekly food delivery service. |
Fixed | Regular schedule | No fixed duration |
SUBSCRIPTION_PREPAID : Subscription plan where the amount due and the billing frequency are fixed. There is no defined duration for the payment due before the goods or services are delivered.SUBSCRIPTION_POSTPAID : Subscription plan where the amount due and the billing frequency are fixed. There is no defined duration for the payment due after the goods or services are delivered.
|
Recurring Represents a recurring payment that charges the payer a variable amount on a regular basis with no specified end date. Examples include a monthly utility bill auto payment. |
Variable | Regular schedule | No fixed duration |
RECURRING_PREPAID : Pay a fixed or variable amount upfront on a fixed date before the goods or services are delivered.RECURRING_POSTPAID : Pay on a fixed date based on usage or consumption after the goods or services are delivered.
|
Unscheduled Represents a recurring payment that charges the payer either a fixed or variable amount on a varying basis with no specified end date. One example could be an auto-reload feature for a prepaid card that activates when the balance falls below a specified amount. Another example is an app store that combines purchases and charges users for spending over a certain amount within a specific timeframe. |
Fixed or variable | Variable | No fixed duration |
UNSCHEDULED_POSTPAID : Merchant-managed installment plan when the amount to be paid and the billing frequency is fixed, but there is a defined number of payments with the payment due after the goods or services are delivered.UNSCHEDULED_PREPAID : Unscheduled card-on-file plan where the merchant can bill the payer upfront based on an agreed logic, but the amount due and frequency can vary. This includes automatic reload plans.
|
Installment Represents a recurring payment that charges the payer a fixed amount with a defined end date. Use this when a merchant can assist the payer in purchasing goods or services and charges them in installments. |
Fixed | Defined schedule | Defined duration |
INSTALLMENT_POSTPAID : Merchant-managed installment plan when the amount to be paid and the billing frequency are fixed, but there is a defined number of payments with the payment due after the goods or services are delivered.INSTALLMENT_PREPAID : Merchant-managed installment plan when the amount to be paid and the billing frequency are fixed, but there is a defined number of payments with the payment due before the goods or services are delivered.
|
Recurring billing plan
The recurring billing plan details are passed in the payment_source.paypal.billing_plan
object of the Create Setup Token API request:
name
: The billing plan name is an optional description used to provide further information to the payer about the service they are purchasing as part of a recurring payment arrangement. This is displayed within the PayPal flow.billing_cycles
: A billing cycle is a set of attributes relating to an amount and duration. 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.
When you save a payment method without purchase, the billing plan object is payment_source.paypal.billing_plan
in the Create Setup Token API call.
When you save a payment method with purchase, pass the billing plan object in the Create Order API call using the purchase_units.items[]
, purchase_units.items[].billing_plan
, and payment_source.paypal.attributes.vault
objects. For more details, see Save payment methods for recurring payments.
Options for providing recurring payment type and recurring billing plan
PayPal’s recurring billing plan structure is designed to support use cases from simple to complex multi-tier arrangements. It is passed using the object billing_plan
.
A merchant has 3 choices regarding passing recurring payment metadata:
Merchant options | Payer experience | Use case |
Pass usage_pattern and paypal.billing_plan.name
|
Recurring approval flow hosted by PayPal is initiated for the payer.
They see the plan details associated with the usage_pattern ,
paypal.billing_plan.name , and other billing plan details.
|
This helps show plan information to the payer at the time of checkout. Example use case: A buyer subscribing to a $5.99/month plan with a 14-day free trial starting today. |
Pass usage_pattern only
|
Recurring approval flow hosted by PayPal is initiated for the payer, but they don't see plan details. |
Complex plan structures can be hard to present on the checkout screen.
The buyer sees a generic recurring checkout flow that does not contain
the details of the plan. The merchant must clearly communicate plan
terms on their site before signup. Example use case: The consumer signs up for a hybrid plan structure that involves usage-based billing at the end of each month, with automated billing within the month when certain thresholds are met. |
Pass neither | Recurring approval flow hosted by PayPal has not started for the payer, and they see the non-recurring PayPal-hosted approval flow. |
Transactions without a recurring component are not recommended
for recurring transactions. Example use case: The consumer saves their payment information for a ride-share app. |
User action button behavior without purchase
You can use the user action setting to control the message displayed on the PayPal button on the review page. There are two options for the button messaging:
User action | Payer experience | Use case |
Setup Now | PayPal sends the payer to the merchant’s confirmation page after approval. | Use this option for the final approval step. This setting works best for typical flows. |
Continue | PayPal redirects the payer to the merchant’s checkout page after approval. | Use this option when the buyer needs to complete additional steps or view more pages after approval. |
User action button behavior with purchase
User action | Payer experience | Use case |
Pay now | The payer completes the transaction on the PayPal review page. | Use this when you want to process payment immediately, such as when the order total is already known and fixed. This reduces steps for the customer and speeds up the checkout process. |
Continue | The payer returns to the merchant site to complete the transaction. | Use this when the final order amount may change after the payer leaves PayPal. This can present a review page before completing the transaction. |
Create setup token during purchase
Use the Create Setup Token API during checkout to securely capture and store a customer’s payment method for recurring transactions.
Modify the code
Use the Create Setup Token API during checkout to securely capture and store a customer’s payment method for recurring transactions.
- Copy the code sample.
- Change
ACCESS-TOKEN
to your sandbox access token. - Change
REQUEST-ID
to a set of unique alphanumeric characters, such as a timestamp. - Use PayPal as the
payment_source
. Pass additional parameters in thepaypal
object for your use case and business. - Add
usage_pattern
under thepayment_source
object and pass thebilling_plan
details. These are the details that the payer sees on the PayPal review page. - Update the
return_url
value with the URL where the payer is redirected after they approve the flow. - Update the
cancel_url
value with the URL where the payer is redirected after they cancel the flow. - Update
user_action
value to confirm the agreement.
Sample Create Setup Token API request
1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \2-H 'Authorization: Bearer ACCESS-TOKEN' \3 -H 'PayPal-Request-ID: PAYPAL-REQUEST-ID' \4 -H 'Content-Type: application/json' \5 -d '{6 "customer": {7 "merchant_customer_id": "payer@example.com"8 },9 "payment_source": {10 "paypal": {11 "permit_multiple_payment_tokens": false,12 "usage_type": "MERCHANT",13 "customer_type": "CONSUMER",14 "usage_pattern": "RECURRING_PREPAID",15 "shipping": {16 "name": {17 "full_name": "Firstname Lastname"18 },19 "address": {20 "address_line_1": "123 Main St.",21 "admin_area_2": "Anytown",22 "admin_area_1": "CA",23 "postal_code": "12345",24 "country_code": "US"25 }26 },27 "billing_plan": {28 "billing_cycles": [29 {30 "tenure_type": "REGULAR",31 "pricing_scheme": {32 "pricing_model": "VARIABLE",33 "price": {34 "value": "6.99",35 "currency_code": "USD"36 }37 },38 "frequency": {39 "interval_unit": "MONTH",40 "interval_count": 141 },42 "total_cycles": 0,43 "sequence": 1,44 "start_date": "2024-04-16"45 }46 ],47 "one_time_charges": {48 "setup_fee": {49 "value": "10",50 "currency_code": "USD"51 },52 "shipping_amount": {53 "value": "3",54 "currency_code": "USD"55 },56 "taxes": {57 "value": "20",58 "currency_code": "USD"59 },60 "product_price": {61 "value": "200",62 "currency_code": "USD"63 },64 "total_amount": {65 "value": "233",66 "currency_code": "USD"67 }68 },69 "product": {70 "description": "Company yearly membership",71 "quantity": "1.0"72 },73 "name": "Company"74 },75 "experience_context": {76 "shipping_preference": "SET_PROVIDED_ADDRESS",77 "locale": "en-US",78 "return_url": "https://example.com/returnUrl",79 "cancel_url": "https://example.com/cancelUrl"80 }81 }82 }83}
Sample Create Setup Token API response
1{2 "id": "SETUP-TOKEN-ID",3 "customer": {4 "id": "CUSTOMER-ID"5 },6 "status": "PAYER_ACTION_REQUIRED",7 "payment_source": {8 "paypal": {9 "usage_pattern": "RECURRING_PREPAID",10 "shipping": {11 "name": {12 "full_name": "Firstname Lastname"13 },14 "address": {15 "address_line_1": "123 Main St.",16 "admin_area_2": "Anytown",17 "admin_area_1": "CA",18 "postal_code": "12345",19 "country_code": "US"20 }21 },22 "permit_multiple_payment_tokens": false,23 "usage_type": "MERCHANT",24 "customer_type": "CONSUMER"25 }26 },27 "links": [{28 "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/SETUP-TOKEN-ID",29 "rel": "self",30 "method": "GET",31 "encType": "application/json"32 }, {33 "href": "https://sandbox.paypal.com/agreements/approve?approval_session_id=SETUP-TOKEN-ID",34 "rel": "approve",35 "method": "GET",36 "encType": "application/json"37 }]38}
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 create-payment-tokens.
Modify the code
- Copy the code sample.
- Change
ACCESS-TOKEN
to your sandbox access token. - Change
PAYPAL-REQUEST-ID
to a unique alphanumeric set of characters, such as a time stamp. - Use
PAYPAL
as thepayment_source
and complete the rest of the source objects for your use case and business.
Sample API request
Create an order with a card as a payment source and store the card in the vault with 3D Secure verification when required.1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/2-H "Content-Type: application/json"3-H "Authorization: Bearer ACCESS-TOKEN"4-d '{5 "intent": "CAPTURE",6 "purchase_units": [7 {8 "amount": {9 "currency_code": "USD",10 "value": "238",11 "breakdown": {12 "item_total": {13 "currency_code": "USD",14 "value": "215"15 },16 "shipping": {17 "currency_code": "USD",18 "value": "3"19 },20 "tax_total": {21 "currency_code": "USD",22 "value": "20"23 }24 }25 },26 "items": [27 {28 "name": "iPhone 13",29 "description": "iPhone 13 with Verizon plan",30 "sku": "259483234816",31 "unit_amount": {32 "currency_code": "USD",33 "value": "200"34 },35 "tax": {36 "currency_code": "USD",37 "value": "20"38 },39 "quantity": "1",40 "category": "DIGITAL_GOODS"41 },42 {43 "name": "Billing Plan",44 "description": "Billing plan for subscriptions",45 "unit_amount": {46 "currency_code": "USD",47 "value": "15"48 },49 "quantity": "1",50 "billing_plan": {51 "name": "Verizon",52 "setup_fee": {53 "value": "10",54 "currency_code": "USD"55 },56 "billing_cycles": [57 {58 "tenure_type": "REGULAR",59 "pricing_scheme": {60 "price": {61 "value": "5",62 "currency_code": "USD"63 },64 "pricing_model": "FIXED"65 },66 "frequency": {67 "interval_unit": "MONTH",68 "interval_count": 169 },70 "total_cycles": 0,71 "sequence": 172 }73 ]74 }75 ]76 }77 ],78 "payment_source": {79 "paypal": {80 "attributes": {81 "vault": {82 "store_in_vault": "ON_SUCCESS",83 "usage_type": "MERCHANT",84 "usage_pattern": "SUBSCRIPTION_PREPAID"85 }86 },87 "experience_context": {88 "return_url": "https://example.com/returnUrl",89 "cancel_url": "https://example.com/cancelUrl"90 }91 }92 }93 }94 }'
Sample API response
1{2 "id": "ORDER-ID",3 "intent": "CAPTURE",4 "status": "PAYER_ACTION_REQUIRED",5 "payment_source": {6 "paypal": {}7 },8 "purchase_units": [9 {10 "items": [11 {12 "name": "iPhone 13",13 "description": "iPhone 13 with Verizon plan",14 "sku": "259483234816",15 "unit_amount": {16 "currency_code": "USD",17 "value": "200"18 },19 "tax": {20 "currency_code": "USD",21 "value": "20"22 },23 "quantity": "1",24 "category": "PHYSICAL_GOODS"25 },26 {27 "name": "Billing Plan",28 "description": "Billing plan for subscriptions",29 "unit_amount": {30 "currency_code": "USD",31 "value": "10"32 },33 "quantity": "1",34 "billing_plan": {35 "name": "Verizon",36 "setup_fee": {37 "value": "10",38 "currency_code": "USD"39 },40 "billing_cycles": [41 {42 "tenure_type": "REGULAR",43 "pricing_scheme": {44 "price": {45 "value": "5",46 "currency_code": "USD"47 },48 "pricing_model": "FIXED"49 },50 "frequency": {51 "interval_unit": "MONTH",52 "interval_count": 153 },54 "total_cycles": 0,55 "sequence": 156 }57 ]58 }59 }60 ],61 "amount": {62 "currency_code": "USD",63 "value": "238.00",64 "breakdown": {65 "item_total": {66 "currency_code": "USD",67 "value": "215.00"68 },69 "tax_total": {70 "currency_code": "USD",71 "value": "20.00"72 },73 "shipping": {74 "currency_code": "USD",75 "value": "3"76 }77 }78 }79 }80 ],81 "links": [82 {83 "href": "https://api-m.paypal.com/v2/checkout/orders/ORDER-ID",84 "rel": "self",85 "method": "GET"86 },87 {88 "href": "https://www.paypal.com/checkoutnow?token=ORDER-ID",89 "rel": "payer-action",90 "method": "GET"91 }92 ]93}
As seen previously, payment_source.card.attributes.vault
has the relevant information in the vault.id
when the vault.status
is VAULTED
. This can be used for subsequent payments.
Use payment method token with checkout
After you create a payment method token, and the buyer agrees to a payment schedule, you can use the token to create merchant-initiated purchases and capture recurring payments with the Create orders endpoint of the Orders v2 API. Use this to charge your buyers for their recurring payments.
Tokenization payment method with purchase
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.
See Save PayPal with the Orders API and Save payment methods for recurring payments for more information.
Modify the code
- Copy the code sample.
- Change
ACCESS-TOKEN
to your sandbox access token. - Change
REQUEST-ID
to a set of unique alphanumeric characters, such as a timestamp. - Use the ID of your payment method token as the
vault_id
. - Specify
intent
to indicate whether to capture a payment immediately or authorize it for a payment later. UseAUTHORIZE
for Auth-Capture. - Add
amount
for the total order. - Update
stored_credential
as the payment source for a vaulted payment method token to provide additional details for recurring transactions that includeusage_pattern
,payment_initiator
, andusage
.
Sample API request
1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/2-H "Content-Type: application/json"3-H "Authorization: Bearer ACCESS_TOKEN"4-d '{5 "intent": "CAPTURE",6 "purchase_units": [7 {8 "amount": {9 "currency_code": "USD",10 "value": "238",11 "breakdown": {12 "item_total": {13 "currency_code": "USD",14 "value": "215"15 },16 "shipping": {17 "currency_code": "USD",18 "value": "3"19 },20 "tax_total": {21 "currency_code": "USD",22 "value": "20"23 }24 }25 },26 "items": [27 {28 "name": "iPhone 13",29 "description": "iPhone 13 with Verizon plan",30 "sku": "259483234816",31 "unit_amount": {32 "currency_code": "USD",33 "value": "200"34 },35 "tax": {36 "currency_code": "USD",37 "value": "20"38 },39 "quantity": "1",40 "category": "DIGITAL_GOODS"41 },42 {43 "name": "Billing Plan",44 "description": "Billing plan for subscriptions",45 "unit_amount": {46 "currency_code": "USD",47 "value": "15"48 },49 "quantity": "1",50 "billing_plan": {51 "name": "Verizon",52 "setup_fee": {53 "value": "10",54 "currency_code": "USD"55 },56 "billing_cycles": [57 {58 "tenure_type": "REGULAR",59 "pricing_scheme": {60 "price": {61 "value": "5",62 "currency_code": "USD"63 },64 "pricing_model": "FIXED"65 },66 "frequency": {67 "interval_unit": "MONTH",68 "interval_count": 169 },70 "total_cycles": 0,71 "sequence": 172 }73 ]74 }75 ]76 }77 ],78 "payment_source": {79 "paypal": {80 "attributes": {81 "vault": {82 "store_in_vault": "ON_SUCCESS",83 "usage_type": "MERCHANT",84 "usage_pattern": "SUBSCRIPTION_PREPAID"85 }86 },87 "experience_context": {88 "return_url": "https://example.com/returnUrl",89 "cancel_url": "https://example.com/cancelUrl"90 }91 }92 }93 }94 }'
Sample API response
1{2 "id": "ORDER_ID",3 "intent": "CAPTURE",4 "status": "PAYER_ACTION_REQUIRED",5 "payment_source": {6 "paypal": {}7 },8 "purchase_units": [9 {10 "items": [11 {12 "name": "iPhone 13",13 "description": "iPhone 13 with Verizon plan",14 "sku": "259483234816",15 "unit_amount": {16 "currency_code": "USD",17 "value": "200"18 },19 "tax": {20 "currency_code": "USD",21 "value": "20"22 },23 "quantity": "1",24 "category": "PHYSICAL_GOODS"25 },26 {27 "name": "Billing Plan",28 "description": "Billing plan for subscriptions",29 "unit_amount": {30 "currency_code": "USD",31 "value": "10"32 },33 "quantity": "1",34 "billing_plan": {35 "name": "Verizon",36 "setup_fee": {37 "value": "10",38 "currency_code": "USD"39 },40 "billing_cycles": [41 {42 "tenure_type": "REGULAR",43 "pricing_scheme": {44 "price": {45 "value": "5",46 "currency_code": "USD"47 },48 "pricing_model": "FIXED"49 },50 "frequency": {51 "interval_unit": "MONTH",52 "interval_count": 153 },54 "total_cycles": 0,55 "sequence": 156 }57 ]58 }59 }60 ],61 "amount": {62 "currency_code": "USD",63 "value": "238.00",64 "breakdown": {65 "item_total": {66 "currency_code": "USD",67 "value": "215.00"68 },69 "tax_total": {70 "currency_code": "USD",71 "value": "20.00"72 },73 "shipping": {74 "currency_code": "USD",75 "value": "3"76 }77 }78 }79 }80 ],81 "links": [82 {83 "href": "https://api-m.paypal.com/v2/checkout/orders/ORDER_ID",84 "rel": "self",85 "method": "GET"86 },87 {88 "href": "https://www.paypal.com/checkoutnow?token=ORDER_ID",89 "rel": "payer-action",90 "method": "GET"91 }92 ]93}
Next steps
You can retrieve a payment token, list all payment tokens, delete a payment token, and more with the Payment Method Tokens API.
Resources
- Save PayPal for purchase later with the JavaScript SDK
- Payment Method Tokens API
- Create Order v2 API