Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

Credit card installments

Learn how to accept credit card purchases in installments.

Paying in installments is the most popular form of credit card purchase in Brazil and Mexico, and widely used in Turkey.

Credit card installments are also available for some Mastercard holders in the United Kingdom, but follow a different integration flow. For more information, see Mastercard Installments UK.

When a shopper makes a purchase in installments, the cost is split into multiple smaller payments, each referred to as an installment. These are charged to the shopper's credit card every 30 days until their purchase has been paid in full. This is popular with shoppers as they receive goods or services immediately, but spread the cost of the purchase over multiple months.

Making an installment purchase requires one API call, and is similar to making a regular credit card payment. The first installment is immediately charged to the shopper's credit card, and all future installments will be charged automatically.

Payment Type 3D Secure supported Refunds Partial Refunds Captures Partial Captures Chargebacks
Credit card Yes, for supported cards. Yes Yes

Brazil and Mexico: Supported

Turkey: Not supported

Yes

 

Yes

You can accept credit card installment payments with:

Integrate with Checkout SDKs

Here we describe how to make installment purchases with our Checkout SDKs.

Before you begin this section, make sure you read and understand our SDK Integration guides.

When you offer installments to your shopper, the SDK renders a selector in your credit card form. Here, the shopper can choose the number of installments they want to pay, up to a maximum that you specify in the /paymentSession call.

To offer installments to your shoppers:

  • Make a /paymentSession call to create a payment session, and include a configuration object with:

    • installments.maxNumberOfInstallments: The maximum number of installments you want to offer the shopper. For more information on how many installments you can offer, see number of installments.

    The example below shows how you would make a 120 Brazilian Real (BRL) purchase that can be paid in a maximum of 6 installments of 20 BRL, using our Checkout SDK for Web.

    In Brazil, you can charge interest to shoppers paying in installments. To do this, add the interest to the amount.value.

    {
      "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
      "sdkVersion":"1.9.5",
      "channel":"Web",
      "amount":{
        "currency":"BRL",
        "value":"12000"
      },
      "reference":"installments test",
      "countryCode":"BR",
      "shopperLocale":"pt_BR",
      "origin":"https://www.yourshop.com",
      "returnUrl":"https://www.yourshop.com/checkout/completed",
      "configuration":{
        "installments":{
          "maxNumberOfInstallments":6
        }
      }
    }

The response contains the paymentSession you need to initialize the SDK.

Integrate with API

In this section we show you the API integration steps for making installment purchase with our API integration.

Before you begin this section, make sure you read and understand our API Integration guide.

Step 1: Collect shopper details

The integration steps for collecting a shopper's card details for installments is the same as for a regular credit card payments.

To collect the shopper's card details, you can either:

Collect with Card Component

To add the Card Component to your payments form:

  1. Create a DOM element, placing it where you want the card form to be rendered:

    <div id="card"></div>
  2. Create an instance of the Card Component, and mount it:

    const card = checkout.create("card", {
        onChange: handleOnChange
    }).mount("#card");
  3. Create a function to listen to and handle the onChange event triggered by the Component:

    function handleOnChange(state, component) {
        state.isValid // true or false.
        state.data
        /* {type: "scheme",
            encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
            encryptedExpiryMonth: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
            encryptedExpiryYear: "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
            encryptedSecurityCode: "adyenjs_0_1_18$MT6ppy0FAMVMLH..."}
        */
    }
  4. When state.isValid is true, collect the encrypted values passed in the state.data

Use the encrypted values to make the payment.

To configure how the Card Component renders in your payment form, see Configuring the Component.

Collect with your own payments form 

If you're using your own payments form, when a shopper chooses to pay by card:

  • Collect the following card details from the shopper in your payment form using Secured Fields:

    If you are PCI Level 1 or 2 certified you can pass raw card data instead.

    Card details Example input
    The card number "4111111111111111"
    The card expiry month "03"
    The card expiry year "30"
    The security code (CVV / CVC) "737"
    Optional: The card holder's name. Do not encrypt this. "J Smith"

Use the encrypted card values passed by the Secured Fields to make the payment.

Step 2: Make payment

To make the installment purchase with our Checkout API:

  • Make a regular credit card payment with a /payments API call, and additionally include: 

    • installments.value: The number of installments. For more information on how many installments you can offer, see number of installments.

    The example below shows how you would make a 120 Brazilian Real (BRL) purchase that will be paid in 6 installments of 20 BRL.

    In Brazil, you can charge the shopper interest for paying in installments. To do this, add the interest to the amount.value.

    {
      "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
      "reference":"installments test",
      "paymentMethod":{
        "type":"scheme",
        "encryptedCardNumber": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        "encryptedExpiryMonth": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        "encryptedExpiryYear": "adyenjs_0_1_18$MT6ppy0FAMVMLH...",
        "encryptedSecurityCode": "adyenjs_0_1_18$MT6ppy0FAMVMLH..."
      },
      "installments":{
        "value":6
      },
      "amount":{
        "currency":"BRL",
        "value":"12000"
      }
    }

    Here we use encrypted card details, generated using the Card Component. If you are PCI Level 1 or 2 certified, you can provide raw card data instead.

If the payment is successful, you receive: 

  • pspReference: Our unique identifier for the transaction.
  • resultCode: Authorised

Step 3: Present payment result

  • Use the resultCode you received from the /payments endpoint to present the shopper with the result of the payment in your website or app. Check our result codes documentation for information on what these mean.

Installment notifications

Accepting notifications is not required if you are accepting installment payments, but we strongly recommend that you do. Each notification has a:

  • pspReference: Identifies which payment is being referred to.
  • eventCode : Indicates the status of the payment.

If you haven't already set up notifications, refer to our notifications documentation for instructions.

Successful purchase

When an installment purchase is successful you receive a notification with:

  • eventCodeAUTHORISATION
  • successtrue

You receive this notification for a successful installment purchase, but not for each installment payment. You can track whether an installment payment is successful with the Settlement detail report. For more information, see Reconcile installment payments.

Number of installments

The number of installments you can offer to your shopper depends on their country:

Country Number of installments
Brazil You choose the number of monthly installments.
Mexico Either 3, 6, 9, 12, or 18 monthly installments.
Turkey Either 2, 3, 6, or 9 monthly installments.

Getting paid

How installment payments are processed, and when you receive the funds, depend on the shopper's country. For more information, refer to the country-specific information for Brazil, or Mexico and Turkey.

Brazil 

In Brazil, you receive funds for each installment as it is settled. There is a settlement delay of 30 days.

We also offer advancements if you need funds sooner. There is an additional fee for this service. Contact your Adyen Account Manager for details. 

For more information on how installments are settled and reconciled in Brazil, see Reconcile installment payments.

Mexico and Turkey

For installment purchases made in Mexico or Turkey, you will receive the funds in-full when the first installment is settled.

You will be charged an additional fee by card schemes for installment purchases in Mexico and Turkey. Contact your Adyen Account Manager for details.

Configuring the Component

Our Card Component has several options you can configure, including properties used for Secured Fields, our JavaScript library that the Card component uses to securely collect and encrypt your shopper's credit card details.

When instantiating the Card Component, you can optionally specify:

  • details: Set an object containing the details array for type: scheme from the /paymentMethods response.
  • enableStoreDetails: Set to true to show the checkbox to save card details for the next payment.
  • hasHolderName: Set to true to request the name of the card holder.
  • holderNameRequired: Set to true to require the card holder name.
  • groupTypes: Defaults to ['mc','visa','amex']. Configure supported card types to facilitate brand recognition used in the Secured Fields onBrand callback. See list of available card types. If a shopper enters a card type not specified in the GroupTypes configuration, the onBrand callback will not be invoked.
  • styles: Set a style object to customize the input fields. See Styling Secured Fields for a list of supported properties.
  • placeholders: Specify the sample values you want to appear for card detail input fields.
// Define style object
var styleObject = {
  base: {
    color: 'black',
    fontSize: '16px',
    fontSmoothing: 'antialiased',
    fontFamily: 'Helvetica'
  },
  error: {
    color: 'red'
  },
  placeholder: {
    color: '#d8d8d8'
  },
  validated: {
    color: 'green'
  }
};
 
const card = checkout.create("card", {
    // Options
    enableStoreDetails: true,
    hasHolderName: true,
    holderNameRequired: true,
    groupTypes: ["visa", "amex"],
    styles: styleObject,
    placeholders: {
        encryptedCardNumber : '4111 1111 1111 1111',
        encryptedExpiryDate : '08/18',
        encryptedSecurityCode : '737'
    }
}).mount("#card");

Testing credit card installments

Before making installment payments with live credit cards, use our test card numbers to test your integration.

In Turkey, you can also test installment purchases using Izyico's test card numbers.

You can check the status of a test installment purchase in your Customer Area > Transactions > Payments.

See also