Recurring payments

JavaScript v4

• Current Braintree SDKs
• Android v5
• iOS v7
• JavaScript v3
• Pre-release versions
• JavaScript v4
• Previous Versions
• Android v4
• iOS v6
• JavaScript v2

Use this guide to set up recurring payments with PayPal on the client side of your Web SDK v4 integration, including how to classify the billing agreement type and pass plan details to your customer during checkout.

Prerequisites

• A Braintree client authorization, such as a client token or tokenization key, used to create your client and PayPal Checkout instances.
• A PayPal Checkout component instance (paypalCheckoutInstance) created through the Web SDK v4 paypal-checkout component.
• A page element to render the PayPal button into, for example <div id="paypal-button"></div>.

Overview

Recurring payments are merchant-initiated payments based on a schedule or other service usage criteria and fall into several categories based on billing frequency and amount. Examples of common recurring payments include:

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

Typically, RBA (Recurring Billing Agreement) payments fall into one of the following payment types, based on duration, amount, and frequency.

Subscription type details

Recurring payments with PayPal use PayPal Billing Agreements through PayPal's Billing Without Purchase Checkout flow. This flow has two stages:

1. Create a billing agreement: After a customer completes PayPal Checkout, PayPal returns a Payment Token, a proxy for the PayPal Billing Agreement ID, to you. Store this Payment Token against the customer's account so you can use it to initiate payments later.
2. Initiate a payment against the billing agreement: When you need to take a payment from your customer, use the Payment Token returned during billing agreement creation to initiate a payment against that PayPal account.

Create a billing agreement

Creating a billing agreement requires two pieces of information:

• Recurring indicator: Flags the billing agreement as intended for future recurring payments and tailors the content in PayPal Checkout to indicate to the customer that this is a recurring payment.
• Recurring Billing Agreement (RBA) plan information: Provides the customer with a key information summary in PayPal Checkout about the recurring arrangement they're entering into with you.

Set the recurring indicator

When you set the recurring indicator, send the value that matches the type of RBA. PayPal uses this information to set indicators sent to payment networks, accurately representing the nature of the customer's agreement with you to comply with payment network regulations. During billing agreement creation, you set the Recurring Indicator through the Braintree plan_type value. During subsequent transactions, you set the Recurring Indicator through the Braintree transaction_source value.

RBA type reference

Set RBA plan information

When you set the RBA Plan Information, PayPal shows your customer a key information summary about the RBA on PayPal's Checkout review page. This helps maintain customer confidence about the nature of the agreement when they reach PayPal Checkout. Pass RBA Plan Information to PayPal only during billing agreement creation, so it's visible to the customer while they interact with PayPal Checkout. Don't pass it in later merchant-initiated payment requests.

PayPal's RBA Plan Information structure is a flexible data structure that supports use cases from simple to complex, multi-tier arrangements. Pass it using the plan_metadata object. You have three choices for passing details about the recurring plan:

1. Pass plan_type and plan_metadata: triggers the recurring checkout UX for the buyer, and shows the plan details passed in plan_metadata. This is a good fit for most recurring merchants, because it shows plan information to the buyer at checkout. Example: a consumer subscribing to a $5.99 per month plan with a 14-day free trial, starting today.
2. Pass plan_type only: triggers the recurring checkout UX for the buyer, but shows no plan details. This fits a small group of merchants with complex plan structures that are difficult to summarize concisely at checkout. Consumers see a generic recurring checkout experience without the plan's details, so you still need to communicate the plan's terms to the buyer on your site before they sign up. Example: a consumer signing up for a hybrid plan that combines usage-based billing at the end of each month with automated billing within the month when usage crosses certain thresholds.
3. Pass neither: PayPal doesn't trigger the recurring checkout UX, and the buyer sees the non-recurring checkout UX instead. This fits transactions without a recurring component and isn't recommended for recurring transactions. Example: a consumer saving their payment information for a ride-share app.

Understand the RBA data structure

The RBA Plan Information data structure in the plan_metadata object supports passing:

• Plan name: an optional description of the product or service the customer is buying from you.
• One-time charges: summarized together within PayPal Checkout. Use these to communicate non-recurring charges the customer incurs when starting the RBA with you, such as a setup fee, or goods ordered as part of a combined purchase and RBA, like a mobile phone ordered when the customer signs up for a wireless service plan.

Plan name

The plan name is optional data that gives the customer more information about the service they're purchasing as part of an RBA. PayPal displays this within Checkout, so if you provide it, make sure it's recognizable and comprehensible to the customer. Don't use this field for generic information or coded data such as SKUs or internal plan IDs.

For example, an ABCStream customer signs up for a $10 per month streaming service plan that ABCStream references internally as plan US-HDMNTH. ABCStream can optionally initiate PayPal Checkout with a plan_metadata.name of "HD Premium - Monthly Plan."

Data element reference

Integrate the flow within Braintree

Classify all transactions as either prepaid or postpaid to make sure PayPal transactions comply with card network rules. To set your preferred transaction type, contact your account manager to enable PREPAID or POSTPAID as the default for recurring billing.

Send the recurring payment request

await paypalCheckoutInstance.createPayment({
  flow: 'checkout', // Required
  amount: 245.0, // Required
  amountBreakdown: {
    // Optional
    itemTotal: '215.00',
    taxTotal: '20.00',
    shipping: '10.00'
  },
  currency: 'USD',
  intent: 'capture',
  billingAgreementDescription: 'Your agreement description',
  requestBillingAgreement: true,
  lineItems: [
    {
      name: 'iphone 111',
      quantity: 1,
      kind: 'debit',
      unitAmount: 200,
      unitTaxAmount: 20,
      description: 'purchase item'
    }
  ],
  planType: 'SUBSCRIPTION',
  planMetadata: {
    billingCycles: [
      {
        billingFrequency: '1',
        billingFrequencyUnit: 'MONTH',
        numberOfExecutions: '1',
        sequence: '1',
        trial: false,
        pricingScheme: {
          pricingModel: 'FIXED',
          price: '5.00'
        }
      }
    ],
    currencyIsoCode: 'USD',
    name: 'Verizon Billing Plan',
    productDescription: 'Billing plan for subscriptions',
    productQuantity: '1',
    oneTimeFeeAmount: '10',
    totalAmount: '15.00'
  }
});

Create the billing agreement

try {
  const CLIENT_TOKEN = "<your-client-token>";
  const PAYMENT_PARAMS = {
  flow: 'vault',
  planType: 'RECURRING',
  planMetadata: {
    billingCycles: [
      {
        billingFrequency: "1",
        billingFrequencyUnit: "MONTH",
        numberOfExecutions: "12",
        sequence: "1",
        startDate: "2024-09-09",
        trial: false,
          pricingScheme: {
          pricingModel: "VARIABLE",
          price: "0",
          reloadThresholdAmount: "0"
        }
      }
    ],
    currencyIsoCode: "USD",
    name: "Netflix with Ads",
    productDescription: "iPhone 13",
    productQuantity: 1,
    oneTimeFeeAmount: "9.99",
    shippingAmount: "1.99",
    productPrice: "19.99",
    taxAmount: "0.59",
    totalAmount: "32.56"
  }
  };

  return paypal.Buttons({
    fundingSource: paypal.FUNDING.PAYPAL,
    createBillingAgreement: function () {
      return paypalCheckoutInstance.createPayment(PAYMENT_PARAMS);
    },
    onApprove: async function (data, actions) {
      const payload = await paypalCheckoutInstance.tokenizePayment(data);
      console.log("Payment Approved:", payload);
      // Submit payload.nonce to your server
    },
    onCancel: function () {
      console.log('PayPal Checkout cancelled');
    },
    onError: function (err) {
      console.log('PayPal Checkout Error:', err);
    }
  }).render('#paypal-button');
  
} catch (err) {
    console.error('Braintree Client Error:', err);
}

A successful billing agreement creation logs Payment Approved: followed by the tokenized payment payload to the console.

Initiate a payment against the billing agreement

To process a payment, first save the customer's PayPal account. Vaulted Payments lets you charge the account later without requiring your customer to be present during the transaction, or to re-authenticate with PayPal when they are present. Use the Payment Token returned during billing agreement creation to initiate a payment against the customer's PayPal account. Pass the returned single-use payment token to Payment Method: Create, and use the returned payment method token for payment creation.

RBA type reference for subsequent transactions

After the merchant provides the correct value, a subsequent transaction can occur. During subsequent transactions, you set the Recurring Indicator through the Braintree transaction_source value.