# Recurring payments module (/limited-release/commerce-platform/accept-payments/standard/customize/recurring-payments-module) 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. To learn more about how to save payment methods, review the [Save PayPal for purchase later with the JavaScript SDK](/limited-release/commerce-platform/accept-payments/save-payments/purchase-later/js-sdk/save-paypal/) or the [Save PayPal with the Payment Method Tokens API](/limited-release/commerce-platform/accept-payments/save-payments/purchase-later/payment-tokens-api/save-paypal/) guide. ### What are recurring payments? [#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. ## Eligibility [#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](/api/orders/v2). * Merchant must be integrated using [Save PayPal with the JavaScript SDK](/sdk/js/v5/save-with-purchase/paypal) or have a server-side, direct-API integration with Orders API to provide the save payment method during the purchase experience. * Merchant must be integrated using [Save PayPal for purchase later with the JavaScript SDK](/sdk/js/v5/save-without-purchase/paypal) or have a server-side, direct-API integration with [Payment Method Tokens API](/api/payment-tokens/save-without-purchase/paypal) to provide the save payment method for a later purchase experience. * JavaScript SDK and API-only server-side integrations are supported. ## How it works [#how-it-works] When a payer signs up for your merchant's 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. Your merchant 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 your merchant provides: * 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 [#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 your merchant needs to charge that payment method, send a [Create Order request](/api/payment-tokens/save-without-purchase/paypal#4-use-saved-payment-token) 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](/v5/save-without-purchase/overview). ### Recurring payment setup with purchase [#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 [#recurring-payment-with-or-without-purchase] Pass the recurring payment type in the appropriate `usage_pattern` field when your merchant sets up the payment method. The field your merchant uses 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 the `payment_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 your merchant 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 [#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 your merchant saves a payment method without purchase, the billing plan object is `payment_source.paypal.billing_plan` in the Create Setup Token API call. When your merchant saves 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](/platforms/checkout/standard/customize/save-payment-methods-for-recurring-payments/). ### Options for providing recurring payment type and recurring billing plan [#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 [#user-action-button-behavior-without-purchase] 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-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 your merchant wants 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 [#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 [#modify-the-code] Use the Create Setup Token API during checkout to securely capture and store a customer's payment method for recurring transactions. 1. Copy the code sample. 2. Change `ACCESS-TOKEN` to your [sandbox access token](/api/rest/authentication). 3. Change `REQUEST-ID` to a set of unique alphanumeric characters, such as a timestamp. 4. Use PayPal as the `payment_source`. Pass additional parameters in the `paypal` object for your use case and business. 5. Add `usage_pattern` under the `payment_source` object and pass the `billing_plan` details. These are the details that the payer sees on the PayPal review page. 6. Update the `return_url` value with the URL where the payer is redirected after they approve the flow. 7. Update the `cancel_url` value with the URL where the payer is redirected after they cancel the flow. 8. Update `user_action` value to confirm the agreement. #### Sample request ```text lineNumbers curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \ -H 'Authorization: Bearer ACCESS-TOKEN' \ -H 'PayPal-Request-ID: PAYPAL-REQUEST-ID' \ -H 'Content-Type: application/json' \ -d '{ "customer": { "merchant_customer_id": "payer@example.com" }, "payment_source": { "paypal": { "permit_multiple_payment_tokens": false, "usage_type": "MERCHANT", "customer_type": "CONSUMER", "usage_pattern": "RECURRING_PREPAID", "shipping": { "name": { "full_name": "Firstname Lastname" }, "address": { "address_line_1": "123 Main St.", "admin_area_2": "Anytown", "admin_area_1": "CA", "postal_code": "12345", "country_code": "US" } }, "billing_plan": { "billing_cycles": [ { "tenure_type": "REGULAR", "pricing_scheme": { "pricing_model": "VARIABLE", "price": { "value": "6.99", "currency_code": "USD" } }, "frequency": { "interval_unit": "MONTH", "interval_count": 1 }, "total_cycles": 0, "sequence": 1, "start_date": "2024-04-16" } ], "one_time_charges": { "setup_fee": { "value": "10", "currency_code": "USD" }, "shipping_amount": { "value": "3", "currency_code": "USD" }, "taxes": { "value": "20", "currency_code": "USD" }, "product_price": { "value": "200", "currency_code": "USD" }, "total_amount": { "value": "233", "currency_code": "USD" } }, "product": { "description": "Company yearly membership", "quantity": "1.0" }, "name": "Company" }, "experience_context": { "shipping_preference": "SET_PROVIDED_ADDRESS", "locale": "en-US", "return_url": "https://example.com/returnUrl", "cancel_url": "https://example.com/cancelUrl" } } } } ``` #### Sample response ```text lineNumbers { "id": "SETUP-TOKEN-ID", "customer": { "id": "CUSTOMER-ID" }, "status": "PAYER_ACTION_REQUIRED", "payment_source": { "paypal": { "usage_pattern": "RECURRING_PREPAID", "shipping": { "name": { "full_name": "Firstname Lastname" }, "address": { "address_line_1": "123 Main St.", "admin_area_2": "Anytown", "admin_area_1": "CA", "postal_code": "12345", "country_code": "US" } }, "permit_multiple_payment_tokens": false, "usage_type": "MERCHANT", "customer_type": "CONSUMER" } }, "links": [{ "href": "https://api-m.sandbox.paypal.com/v3/vault/setup-tokens/SETUP-TOKEN-ID", "rel": "self", "method": "GET", "encType": "application/json" }, { "href": "https://sandbox.paypal.com/agreements/approve?approval_session_id=SETUP-TOKEN-ID", "rel": "approve", "method": "GET", "encType": "application/json" }] } ``` 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](/api/payment-tokens/v3#payment-tokens_create). ### Modify the code [#modify-the-code-1] 1. Copy the code sample. 2. Change `ACCESS-TOKEN` to your sandbox access token. 3. Change `PAYPAL-REQUEST-ID` to a unique alphanumeric set of characters, such as a time stamp. 4. Use `paypal` as the `payment_source` and complete the rest of the source objects for your use case and business. ### Sample Create Order API request [#sample-create-order-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. #### Sample request ```text lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ -H "Content-Type: application/json" -H "Authorization: Bearer ACCESS-TOKEN" -d '{ "intent": "CAPTURE", "purchase_units": [ { "amount": { "currency_code": "USD", "value": "238", "breakdown": { "item_total": { "currency_code": "USD", "value": "215" }, "shipping": { "currency_code": "USD", "value": "3" }, "tax_total": { "currency_code": "USD", "value": "20" } } }, "items": [ { "name": "iPhone 13", "description": "iPhone 13 with Verizon plan", "sku": "259483234816", "unit_amount": { "currency_code": "USD", "value": "200" }, "tax": { "currency_code": "USD", "value": "20" }, "quantity": "1", "category": "DIGITAL_GOODS" }, { "name": "Billing Plan", "description": "Billing plan for subscriptions", "unit_amount": { "currency_code": "USD", "value": "15" }, "quantity": "1", "billing_plan": { "name": "Verizon", "setup_fee": { "value": "10", "currency_code": "USD" }, "billing_cycles": [ { "tenure_type": "REGULAR", "pricing_scheme": { "price": { "value": "5", "currency_code": "USD" }, "pricing_model": "FIXED" }, "frequency": { "interval_unit": "MONTH", "interval_count": 1 }, "total_cycles": 0, "sequence": 1 } ] } ] } ], "payment_source": { "paypal": { "attributes": { "vault": { "store_in_vault": "ON_SUCCESS", "usage_type": "MERCHANT", "usage_pattern": "SUBSCRIPTION_PREPAID" } }, "experience_context": { "return_url": "https://example.com/returnUrl", "cancel_url": "https://example.com/cancelUrl" } } } } }' ``` #### Sample response ```text lineNumbers { "id": "ORDER-ID", "intent": "CAPTURE", "status": "PAYER_ACTION_REQUIRED", "payment_source": { "paypal": {} }, "purchase_units": [ { "items": [ { "name": "iPhone 13", "description": "iPhone 13 with Verizon plan", "sku": "259483234816", "unit_amount": { "currency_code": "USD", "value": "200" }, "tax": { "currency_code": "USD", "value": "20" }, "quantity": "1", "category": "PHYSICAL_GOODS" }, { "name": "Billing Plan", "description": "Billing plan for subscriptions", "unit_amount": { "currency_code": "USD", "value": "10" }, "quantity": "1", "billing_plan": { "name": "Verizon", "setup_fee": { "value": "10", "currency_code": "USD" }, "billing_cycles": [ { "tenure_type": "REGULAR", "pricing_scheme": { "price": { "value": "5", "currency_code": "USD" }, "pricing_model": "FIXED" }, "frequency": { "interval_unit": "MONTH", "interval_count": 1 }, "total_cycles": 0, "sequence": 1 } ] } } ], "amount": { "currency_code": "USD", "value": "238.00", "breakdown": { "item_total": { "currency_code": "USD", "value": "215.00" }, "tax_total": { "currency_code": "USD", "value": "20.00" }, "shipping": { "currency_code": "USD", "value": "3" } } } } ], "links": [ { "href": "https://api-m.paypal.com/v2/checkout/orders/ORDER-ID", "rel": "self", "method": "GET" }, { "href": "https://www.paypal.com/checkoutnow?token=ORDER-ID", "rel": "payer-action", "method": "GET" } ] } ``` 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 [#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](/api/orders/v2/orders-create) endpoint of the Orders v2 API. Use this to charge your buyers for their recurring payments. ### Tokenization payment method with purchase [#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 Orders API](/api/orders-v2/save-with-purchase/paypal) and [Save payment methods for recurring payments](/platforms/checkout/standard/customize/save-payment-methods-for-recurring-payments/) for more information. ### Modify the code [#modify-the-code-2] 1. Copy the code sample. 2. Change `ACCESS-TOKEN` to your [sandbox access token](/api/rest/authentication). 3. Change `REQUEST-ID` to a set of unique alphanumeric characters, such as a timestamp. 4. Use the ID of your payment method token as the `vault_id`. 5. Specify `intent` to indicate whether to capture a payment immediately or authorize it for a payment later. Use `AUTHORIZE` for Auth-Capture. 6. Add `amount` for the total order. 7. 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`. #### Sample request ```text lineNumbers curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ -H "Content-Type: application/json" -H "Authorization: Bearer ACCESS_TOKEN" -d '{ "intent": "CAPTURE", "purchase_units": [ { "amount": { "currency_code": "USD", "value": "238", "breakdown": { "item_total": { "currency_code": "USD", "value": "215" }, "shipping": { "currency_code": "USD", "value": "3" }, "tax_total": { "currency_code": "USD", "value": "20" } } }, "items": [ { "name": "iPhone 13", "description": "iPhone 13 with Verizon plan", "sku": "259483234816", "unit_amount": { "currency_code": "USD", "value": "200" }, "tax": { "currency_code": "USD", "value": "20" }, "quantity": "1", "category": "DIGITAL_GOODS" }, { "name": "Billing Plan", "description": "Billing plan for subscriptions", "unit_amount": { "currency_code": "USD", "value": "15" }, "quantity": "1", "billing_plan": { "name": "Verizon", "setup_fee": { "value": "10", "currency_code": "USD" }, "billing_cycles": [ { "tenure_type": "REGULAR", "pricing_scheme": { "price": { "value": "5", "currency_code": "USD" }, "pricing_model": "FIXED" }, "frequency": { "interval_unit": "MONTH", "interval_count": 1 }, "total_cycles": 0, "sequence": 1 } ] } ] } ], "payment_source": { "paypal": { "attributes": { "vault": { "store_in_vault": "ON_SUCCESS", "usage_type": "MERCHANT", "usage_pattern": "SUBSCRIPTION_PREPAID" } }, "experience_context": { "return_url": "https://example.com/returnUrl", "cancel_url": "https://example.com/cancelUrl" } } } } }' ``` #### Sample response ```text lineNumbers { "id": "ORDER_ID", "intent": "CAPTURE", "status": "PAYER_ACTION_REQUIRED", "payment_source": { "paypal": {} }, "purchase_units": [ { "items": [ { "name": "iPhone 13", "description": "iPhone 13 with Verizon plan", "sku": "259483234816", "unit_amount": { "currency_code": "USD", "value": "200" }, "tax": { "currency_code": "USD", "value": "20" }, "quantity": "1", "category": "PHYSICAL_GOODS" }, { "name": "Billing Plan", "description": "Billing plan for subscriptions", "unit_amount": { "currency_code": "USD", "value": "10" }, "quantity": "1", "billing_plan": { "name": "Verizon", "setup_fee": { "value": "10", "currency_code": "USD" }, "billing_cycles": [ { "tenure_type": "REGULAR", "pricing_scheme": { "price": { "value": "5", "currency_code": "USD" }, "pricing_model": "FIXED" }, "frequency": { "interval_unit": "MONTH", "interval_count": 1 }, "total_cycles": 0, "sequence": 1 } ] } } ], "amount": { "currency_code": "USD", "value": "238.00", "breakdown": { "item_total": { "currency_code": "USD", "value": "215.00" }, "tax_total": { "currency_code": "USD", "value": "20.00" }, "shipping": { "currency_code": "USD", "value": "3" } } } } ], "links": [ { "href": "https://api-m.paypal.com/v2/checkout/orders/ORDER_ID", "rel": "self", "method": "GET" }, { "href": "https://www.paypal.com/checkoutnow?token=ORDER_ID", "rel": "payer-action", "method": "GET" } ] } ``` ## Next steps [#next-steps] You can [retrieve a payment token](/api/payment-tokens/v3#payment-tokens_get), [list all payment tokens](/api/payment-tokens/v3#customer_payment-tokens_get), [delete a payment token](/api/payment-tokens/v3#payment-tokens_delete), and more with the Payment Method Tokens API. ## Resources [#resources] * [Save PayPal for purchase later with the JavaScript SDK](/limited-release/commerce-platform/accept-payments/save-payments/purchase-later/js-sdk/save-paypal/) * [Payment Method Tokens API](/api/payment-tokens/v3#payment-tokens_create)