Recurring payments

JavaScript v3SDK

• Current Braintree SDKs
• Android v5
• iOS v6
• JavaScript v3
• Previous Versions
• Android v4
• iOS v5
• JavaScript v2

Availability

Client-side integration for Recurring payments is currently available for

• Web: v3+
• iOS: v6+
• Android: v5+

Recurring payments is similar to vaulted payments during client-side integration. Vaulted Payments has added the feature of the App Switch.

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

Typically, RBA (Recurring billing agreement) payments are classified into one of the following payment types, based on duration, amount, and frequency.

Subscription Type Details

Recurring payments with PayPal utilize PayPal Billing Agreements through PayPal's Billing Without Purchase Checkout flow. PayPal's Billing Without Purchase Checkout flow is a two-stage process:

1. Create a billing agreement: After a customer completes PayPal Checkout, a Payment Token, a proxy for the PayPal Billing Agreement ID, will be returned to you. This Payment Token should be stored against that customer's account and can subsequently be used to initiate payments whenever necessary.
2. Initiating 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.

• Recurring indicator: This is used to flag the billing agreement as intended for use in future recurring payments and tailor the content in the PayPal Checkout to indicate to the customer that this will be a recurring payment.
• Recurring billing agreement (RBA) plan information: This is used to provide the customer with a key information summary in PayPal Checkout of the recurring arrangement they are entering into with you.

Recurring indicator

When setting the recurring indicator, ensure you send the value most appropriate to the type of Recurring Billing Arrangement (RBA). This information is used to set indicators sent to payment networks, accurately representing the nature of the customer's agreement with you to ensure compliance with payment network regulations. During billing agreement creation, the Recurring Indicator is set through the Braintree plan_type value. During subsequent transactions, the Recurring Indicator is set through the Braintree transaction_source value:

RBA type information

Recurring Billing Agreement (RBA) Plan Information

Setting the RBA Plan Information will result in your customer being presented with a key information summary about the RBA they are entering into with you on PayPal's Checkout review page. This is intended to increase conversion at checkout by maintaining customer confidence about the nature of the agreement when they enter PayPal's Checkout. RBA Plan Information is only required to be passed to PayPal during Billing Agreement creation so that this is visible to the customer when they're interacting with PayPal Checkout. It should not be passed in subsequent merchant initiated payment requests to PayPal. PayPal's RBA Plan Information structure is a flexible data structure designed to support use cases from simple to complex multi-tier arrangements. It is passed using the object plan_metadata. A merchant has three choices regarding passing details about the recurring plan:

1. Pass plan_type and plan_metadata → recurring checkout UX is triggered for the buyer, and they are shown the plan details passes in plan_metadata
   • This will be a good fit for most recurring merchants, as it enables showing plan information to the buyer at the time of checkout.
   • Example use case: Consumer subscribing to a $5.99/month plan with a 14-day free trial, starting today
2. Pass plan_type only → recurring checkout UX is triggered for the buyer, but no plan details are shown
   • This will fit a small group of merchants with complex plan structures that may be more difficult to communicate concisely at the checkout screen. Consumers will see a generic recurring checkout experience that does not contain the plan's details. Merchant is still required to clearly communicate the terms of the plan to the buyer on their site prior to completing the signup.
   • Example use case: Consumer signing up to a hybrid plan structure involving usage-based billing at the end of each month, plus automated billing within the month when certain usage thresholds are met
3. Pass neither → recurring checkout UX is not triggered. Buyer sees the non-recurring checkout UX
   • This will be a fit for transactions without a recurring component. It is not recommended for Recurring Transactions.
   • Example use case: consumer saves their payment information for a ride-share app

Understanding the RBA data structure

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

• Plan Name - an optional description of the product/service the customer is buying from you
• One-Time charges - One-Time charges are summarized together within the PayPal Checkout. They are used to pass information related to non-recurring charges the customer will incur when initiating the RBA with you. For example, this could be used to communicate charges such as:
  • Set-Up Fees
  • Goods are ordered as part of a combined purchase and RBA, such as a mobile phone, ordered when the customer signs up for a wireless service plan.

Plan Name

The plan name is optional data used to provide further information to the customer about the service they are purchasing as part of an RBA. This is displayed within the PayPal Checkout, so if provided this should be recognizable and comprehensible by the customer. Do not use this field to provide generic information or coded data such as SKUs or internal plan IDs. Example:

• ABCStream customer is signing up for a $10/month streaming service plan which is internally referenced by ABCStream as plan US-HDMNTH.
• ABCStream may optionally initiate PayPal Checkout with a plan_metadata.name of "HD Premium - Monthly Plan”.

Data Element Information

Integrating flow within Braintree

Merchants must classify all transactions as either prepaid or postpaid to ensure 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.

Create the billing agreement

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: function (data, actions) {
      return paypalCheckoutInstance.tokenizePayment(data).then(function (payload) {
        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(function (err) {
    console.error('Braintree Client Error:', err);
    });

Initiate a payment against the billing agreement:

To process a payment from your customer, use the Payment Token returned during Billing Agreement creation to initiate a payment against that PayPal account.

RBA Type Information During Subsequent Transactions

Once the merchant provides the correct value, a subsequent transaction can occur. During subsequent transactions, the Recurring Indicator is set via the Braintree transaction_source value.