Create an installment payment

Create multiple payments linked to the same installment plan, defining the number and amount of the installments.

When to use

Use installment payments when the total amount needs to be split into two or more payments.

The installment plan can be created with payment methods such as bank slip (boleto), Pix, or credit card, according to the rules applicable to each flow.

Before you start

You need to:

1. register or look up the customer;
2. store the ID returned by the API;
3. define the payment method;
4. define the number of installments;
5. choose how the amount will be calculated.

See: Register customers to create payments.

How it works

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Register or look up the customer"] --> B["Define the number of installments"]
    B --> C{"How will the amount be provided?"}

    C --> CParcela(("Per installment"))
    C --> CTotal(("Total amount"))

    CParcela --> D["Provide installmentValue"]
    CTotal --> E["Provide totalValue"]

    D --> F["Create the installment plan"]
    E --> F

    F --> G["Store the ID returned in installment"]
    G --> H["Retrieve all installments"]
    H --> I["Track the payments"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

    classDef respostaParcela fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px
    classDef respostaTotal fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px

    class A inicio
    class C decisao
    class B,D,E,F,G,H validacao
    class I sucesso

    class CParcela respostaParcela
    class CTotal respostaTotal

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 2 stroke:#8B5CF6,stroke-width:4px
    linkStyle 3 stroke:#22C55E,stroke-width:4px

1. Define how installments are calculated

There are two ways to provide the amount:

When totalValue cannot be divided evenly, the difference will be applied to the last installment.

2. Create the installment plan

Send a request to:

POST /v3/payments

Defining the amount of each installment

{
  "customer": "cus_000005219613",
  "billingType": "BOLETO",
  "installmentCount": 6,
  "installmentValue": 20.00,
  "dueDate": "2027-01-15",
  "description": "Order 056984",
  "externalReference": "056984"
}

Defining the total amount

Replace installmentValue with totalValue:

{
  "customer": "cus_000005219613",
  "billingType": "BOLETO",
  "installmentCount": 12,
  "totalValue": 350.00,
  "dueDate": "2027-01-15",
  "description": "Order 056984",
  "externalReference": "056984"
}

See the endpoint: Create new payment.

You can also include discount, interest, and fine according to the payment method used. See the reference to check the available fields and rules.

Expected result

If successful, the API will return the first payment generated.

Store:

• id: identifier of the returned payment;
• installment: installment plan identifier;
• installmentNumber: installment number;
• status: current status of the payment.

3. Retrieve all installments

Use the ID returned in the installment field:

GET /v3/installments/{id}/payments

Example:

GET /v3/installments/5a2c890b-dd63-4b5a-9169-96c8d7828f4c/payments

See the endpoint: List payments of an installment.

Each installment has its own:

• payment ID;
• due date;
• amount;
• number;
• status.

Store these identifiers to track and reconcile each payment individually.

Credit card installments

The installment limits are:

• up to 21 installments for Visa and Mastercard cards;
• up to 12 installments for other card brands.

See Payments via credit card to learn how to send the card details or the creditCardToken.

Track the payments

Each installment has its own lifecycle.

Configure Webhooks to track status changes, payments, due dates, and refunds.

See:

• Configure Webhooks
• Events for payments

Common errors

If the installment plan is not created, check whether:

• installmentCount has two or more installments;
• installmentValue or totalValue was sent;
• the two amount fields were not sent at the same time;
• the customer belongs to the same account;
• the due date is in the expected format;
• the card brand limit was respected;
• the ID used in the listing belongs to the installment plan, not to an individual payment.

Next steps

• See the endpoint: Create new payment
• List the payments of an installment plan
• Retrieve an installment plan
• Generate the installment booklet
• Create payments via bank slip
• Create payments via credit card
• Understand refunds