Recurring payments module

Current

Last updated: Jan 14th, 3:23pm

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 guide.

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 one-time 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.

To set up the recurring payment module, pass additional fields in the Create Setup Token API request. The payer 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 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 type

Pass the recurring payment type in the payment_source.paypal.usage_pattern field of the create setup token request to set the payment method. 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.

Merchant options

Payer experience

Use case

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.

FixedRegular scheduleNo 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 of this could be a monthly utility bill auto payment.

VariableRegular scheduleNo fixed duration

RECURRING_PREPAID : Pay a fixed or variable amount upfront on a fixed date before the goods or services are delivered.

SUBSCRIPTION_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 variableVariableNo 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.

FixedDefined scheduleDefined 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 gods 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.

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.nameRecurring 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 onlyRecurring 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. A merchant needs to clearly communicate the terms of the plan to the payer on their site prior to completing signup.

Example use case: The consumer signs up for a hybrid plan structure that involves usage-based billing at the end of each month. There is automated billing within the month when certain usage thresholds are met.

Pass neitherRecurring approval flow hosted by PayPal is not started for the payer, and the payer sees 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.

Tokenization payment method

Modify the code

  1. Copy the code sample.
  2. Change ACCESS-TOKEN to your sandbox access token.
  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.

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: REQUEST-ID' \
4-H 'Content-Type: application/json' \
5-d '{
6    "customer": {
7        "merchant_customer_id": "buyer@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": 1
41                        },
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": "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://msmaster.qa.paypal.com/v3/vault/setup-tokens/TOKEN-ID",
29    "rel": "self",
30    "method": "GET",
31    "encType": "application/json"
32  }, {
33    "href": "https://msmaster.qa.paypal.com/agreements/approve?approval_session_id=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.

Create a payment method 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.

Modify the code

  1. Copy the code sample.
  2. Change ACCESS-TOKEN to your sandbox access token.
  3. Change REQUEST-ID to a unique alphanumeric set of characters, such as a time stamp.
  4. Use token as the payment_source and complete the rest of the source objects for your use case and business.
  5. Use your setup token ID to pass in the payment source parameter and type as the SETUP-TOKEN.

Sample API request

1curl -v -k -X POST https://api-m.sandbox.paypal.com/v3/vault/payment-tokens \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: Bearer ACCESS-TOKEN' \
4 -H 'PayPal-Request-Id: REQUEST-ID' \
5 -d '{
6      "payment_source": {
7          "token": {
8              "id": "TOKENIZED-PAYMENT-SOURCE",
9              "type": "SETUP_TOKEN"
10          }
11      }
12  }'

Sample API response

1{
2  "id": "TOKEN-ID",
3  "customer": {
4    "id": "CUSTOMER-ID"
5  },
6  "payment_source": {
7    "paypal": {
8      "description": "Description for PayPal to be shown to PayPal payer",
9      "usage_pattern": "RECURRING_POSTPAID",
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      "email_address": "merchant@example.com",
26      "payer_id": "PAYER-ID"
27    }
28  },
29  "links": [{
30    "rel": "self",
31    "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/TOKEN-ID",
32    "method": "GET",
33    "encType": "application/json"
34  }, {
35    "rel": "delete",
36    "href": "https://api-m.sandbox.paypal.com/v3/vault/payment-tokens/TOKEN-ID",
37    "method": "DELETE",
38    "encType": "application/json"
39  }]
40}

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 Order API. Use this to charge your buyers for their recurring payments.

Modify the code

  1. Copy the code sample.
  2. Change ACCESS-TOKEN to your sandbox access token.
  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 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": "AUTHORIZE",
6            "purchase_units": [
7                {
8                 "description": "HD Premium Plan",
9                  "invoice_id": "test-invoice-id",
10                  "amount": {
11                        "currency_code": "USD",
12                        "value": "100.00"
13                    }
14                }
15            ],
16            "payment_source": {
17                "paypal": {
18                    "vault_id": "TOKEN-ID",
19                    "stored_credential": {
20                        "payment_initiator": "MERCHANT",
21                        "usage": "SUBSEQUENT",
22                        "usage_pattern": "RECURRING_POSTPAID" 
23                    }
24                }
25            }
26        }
27}'

Sample API response

1{
2  "id": "ORDER-ID",
3  "intent": "AUTHORIZE",
4  "status": "COMPLETED",
5  "payment_source": {
6    "paypal": {
7      "email_address": "buyer@example.com",
8      "account_id": "buyer-account",
9      "account_status": "UNVERIFIED",
10      "name": {
11        "given_name": "Firstname",
12        "surname": "Lastname"
13      },
14      "address": {
15        "country_code": "US"
16      },
17      "stored_credential": {
18        "payment_initiator": "MERCHANT",
19        "usage_pattern": "RECURRING_POSTPAID",
20        "usage": "SUBSEQUENT"
21      }
22    }
23  },
24  "purchase_units": [{
25    "reference_id": "default",
26    "amount": {
27      "currency_code": "USD",
28      "value": "100.00"
29    },
30    "payee": {
31      "email_address": "merchant@example.com",
32      "merchant_id": "TEST-MERCHANT-ID"
33    },
34    "description": "HD Premium Plan",
35    "invoice_id": "test-invoice-id",
36    "soft_descriptor": "PAYPAL *TEST STORE",
37    "payments": {
38      "authorizations": [{
39        "status": "CREATED",
40        "id": "AUTHORIZATION-ID",
41        "amount": {
42          "currency_code": "USD",
43          "value": "100.00"
44        },
45        "invoice_id": "test-invoice-id",
46        "seller_protection": {
47          "status": "ELIGIBLE",
48          "dispute_categories": ["ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION"]
49        },
50        "expiration_time": "2024-11-29T15:49:26Z",
51        "links": [{
52          "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID",
53          "rel": "self",
54          "method": "GET"
55        }, {
56          "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/capture",
57          "rel": "capture",
58          "method": "POST"
59        }, {
60          "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/void",
61          "rel": "void",
62          "method": "POST"
63        }, {
64          "href": "https://api.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/reauthorize",
65          "rel": "reauthorize",
66          "method": "POST"
67        }, {
68          "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
69          "rel": "up",
70          "method": "GET"
71        }],
72        "create_time": "2024-10-31T15:49:26Z",
73        "update_time": "2024-10-31T15:49:26Z"
74      }]
75    }
76  }],
77  "payer": {
78    "name": {
79      "given_name": "Firstname",
80      "surname": "Lastname"
81    },
82    "email_address": "buyer@example.com",
83    "payer_id": "test-payer-id",
84    "address": {
85      "country_code": "US"
86    }
87  },
88  "create_time": "2024-10-31T15:49:24Z",
89  "update_time": "2024-10-31T15:49:26Z",
90  "links": [{
91    "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
92    "rel": "self",
93    "method": "GET"
94  }]
95}

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