Accepting card payments in installments

Learn how to accept credit card payments using an installment plan with Elements and the Payment Intents API.

Installments is a feature of consumer credit cards in some markets (known as meses sin intereses in Mexico) that allows customers to split purchases over multiple billing statements. You receive the full amount (minus a fee) as if it were a normal charge, and the customer’s bank handles collecting the money over time.

Installments is available for all users in Mexico.

Installments Quickstart

Accepting Installments uses the Payment Intents API. It requires collecting payment details and Installment plan information on the client and completing the payment on the server.

A diagram showing the collection of card details, creation of the PaymentIntent, selection of installment plan, and confirmation of the payment

Collect payment method details on the client
Retrieve Installment plans on the server
Select an Installment plan on the client
Confirm the PaymentIntent on the server

Collect payment method details on the client

The Payment Intents API works with Stripe.js & Elements to securely collect payment information (e.g., credit card details) on the client side. To get started with Elements, include the following script on your pages. This script must always load directly from js.stripe.com in order to remain PCI compliant—you can’t include it in a bundle or host a copy of it yourself.

<script src="https://js.stripe.com/v3/"></script>

To securely collect card details from your customers, Elements creates UI components for you that are hosted by Stripe. They are then placed into your payment form, rather than you creating them directly. To determine where to insert these components, create empty DOM elements (containers) with unique IDs within your payment form.

index.html

<div id="details">
  <input id="cardholder-name" type="text" placeholder="Cardholder name">
  <!-- placeholder for Elements -->
  <form id="payment-form">
    <div id="card-element"></div>
    <button id="card-button">Next</button>
  </form>
</div>

Next, create an instance of the Stripe object, providing your publishable API key as the first parameter, and then create an instance of the Elements object. Use the newly created object to mount a Card element in the relevant placeholder in the page.

client.js

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

var elements = stripe.elements();
var cardElement = elements.create('card');
cardElement.mount('#card-element');

Finally, use stripe.createPaymentMethod on your client to collect the card details and create a PaymentMethod when the user clicks the submit button.

client.js

var cardholderName = document.getElementById('cardholder-name');
var form = document.getElementById('payment-form');

form.addEventListener('submit', function(ev) {
  ev.preventDefault();
  stripe.createPaymentMethod({
    type: 'card',
    card: cardElement,
    billing_details: {name: cardholderName.value}
  }).then(function(result) {
    if (result.error) {
      // Show error in payment form
    } else {
      // Otherwise send paymentMethod.id to your server (see Step 2)
      fetch('/collect_details', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ payment_method_id: result.paymentMethod.id })
      }).then(function(result) {
        // Handle server response (see Step 3)
        result.json().then(function(json) {
          handleInstallmentPlans(json);
        })
      });
    }
  });
});

Retrieve Installment plans on the server

To retrieve available installment plans, set up an endpoint on your server to receive the request.

Create a new PaymentIntent with the ID of the PaymentMethod created on your client. Set payment_method_options.card.installments.enabled=true to allow this payment to use Installments. Send the available plans to the client so the customer can select which plan to pay with.

You should not confirm the PaymentIntent here (i.e., you should not set the confirm property) because we do not know if the user wants to pay with Installments yet.

Terminal

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method"="pm_card_mx" \
  -d "amount"=3099 \
  -d "currency"="mxn" \
  -d "payment_method_options[card][installments][enabled]"="true"

The PaymentIntent object lists the available installment plans for the PaymentMethod under payment_method_options.card.installments.available_plans.

{
  "id": "pi_1FKDPTJXdud1yP2PpUXNgq0V",
  "object": "payment_intent",
  "amount": 3099,
...
  "payment_method_options": {
    "card": {
      "installments": {
        "enabled": true,
        "plan": null,
        "available_plans": [
          {
            "count": 3,
            "interval": "month",
            "type": "fixed_count"
          },

Select an Installment plan on the client

Allow the customer to select the Installments plan they want to use.

index.html

<div id="plans" hidden>
  <form id="installment-plan-form" >
    <label><input id="immediate-plan" type="radio" name="installment_plan" value="-1" />Immediate</label>
    <input id="payment-intent-id" type="hidden" />
  </form>
  <button id="confirm-button">Confirm Payment</button>
</div>

<div id="result" hidden>
  <p id="status-message"></p>
</div>

client.js

const selectPlanForm = document.getElementById('installment-plan-form');
let availablePlans = [];

const handleInstallmentPlans = async (response) => {
  if (response.error) {
    // Show error from server on payment form
  } else {
    // Store the payment intent ID.
    document.getElementById('payment-intent-id').value = response.intent_id;
    availablePlans = response.available_plans;

    // Show available installment options
    availablePlans.forEach((plan, idx) => {
      const newInput = document.getElementById('immediate-plan').cloneNode();
      newInput.setAttribute('value', idx);
      newInput.setAttribute('id', '');
      const label = document.createElement('label');
      label.appendChild(newInput);
      label.appendChild(
        document.createTextNode(`${plan.count} ${plan.interval}s`),
      );

      selectPlanForm.appendChild(label);
    });

    document.getElementById('details').hidden = true;
    document.getElementById('plans').hidden = false;
  }
};

Send the selected plan to your server.

client.js

const confirmButton = document.getElementById('confirm-button');

confirmButton.addEventListener('click', async (ev) => {
  const selectedPlanIdx = selectPlanForm.installment_plan.value;
  const selectedPlan = availablePlans[selectedPlanIdx];
  const intentId = document.getElementById('payment-intent-id').value;
  const response = await fetch('/confirm_payment', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      payment_intent_id: intentId,
      selected_plan: selectedPlan,
    }),
  });

  const responseJson = await response.json();

  // Show success / error response.
  document.getElementById('plans').hidden = true;
  document.getElementById('result').hidden = false;

  var message;
  if (responseJson.status === "succeeded" && selectedPlan !== undefined) {
    message = `Success! You made a charge with this plan:${
      selectedPlan.count
    } ${selectedPlan.interval}`;
  } else if (responseJson.status === "succeeded") {
    message = "Success! You paid immediately!";
  } else {
    message = "Uh oh! Something went wrong";
  }

  document.getElementById("status-message").innerText = message;
});

Confirm the PaymentIntent on the server

Using another server endpoint, confirm the PaymentIntent to finalize the payment and fulfill the order.

Terminal

curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/confirm \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "payment_method_options[card][installments][plan][type]"="fixed_count" \
  -d "payment_method_options[card][installments][plan][interval]"="month" \
  -d "payment_method_options[card][installments][plan][count]"=3

The response from the server will indicate that you selected the plan on the PaymentIntent and also on the resulting charge.

{
  "id": "pi_1FKDPFJXdud1yP2PMSXLlPbg",
  "object": "payment_intent",
  "amount": 3099,
...
  "charges": {
    "data": [
      {
        "id": "ch_1FKDPHJXdud1yP2P2u79mcIX",
        "object": "charge",
        "amount": 3099,
        "payment_method_details": {
          "card": {
            "installments": {
              "plan": {
                "count": 3,
                "interval": "month",
                "type": "fixed_count"
              }
            },

Test the integration

You can use the following cards to test your integration:

Number	Description
	3, 6, 9, 12, 18, and 24 month installment plans available
	No installment plans available.

Requirements

There are restrictions on which transactions and cards can use installments. You don’t need to implement these rules yourself. The Payment Intents API automatically determines Installments eligibility after a payment method has been attached.

Stripe only supports installments in Mexico.
The payment method must be a credit card issued in Mexico.
The card must be a consumer card (corporate cards are not supported).
The card must be issued by one of our supported issuers (listed on the right).
The currency value must be MXN.
The total payment amount must be above a minimum amount, based on the number of months in the plan selected:

Installment Plan	Minimum Amount
3 months	$300.00 MXN
6 months	$600.00 MXN
9 months	$900.00 MXN
12 months	$1,200.00 MXN
18 months	$1,800.00 MXN
24 months	$2,400.00 MXN