Criar uma cobrança parcelada

Crie várias cobranças vinculadas ao mesmo parcelamento, definindo a quantidade e o valor das parcelas.

Quando utilizar

Utilize cobranças parceladas quando o valor total precisar ser dividido em duas ou mais cobranças.

O parcelamento pode ser criado com formas de pagamento como boleto, Pix ou cartão de crédito, conforme as regras aplicáveis a cada fluxo.

Antes de começar

Você precisa:

1. cadastrar ou localizar o cliente;
2. armazenar o ID retornado pela API;
3. definir a forma de pagamento;
4. definir a quantidade de parcelas;
5. escolher como o valor será calculado.

Consulte: Cadastre clientes para criar cobranças.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Cadastrar ou localizar o cliente"] --> B["Definir a quantidade de parcelas"]
    B --> C{"Como o valor será informado?"}

    C --> CParcela(("Por parcela"))
    C --> CTotal(("Valor total"))

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

    D --> F["Criar o parcelamento"]
    E --> F

    F --> G["Armazenar o ID retornado em installment"]
    G --> H["Recuperar todas as parcelas"]
    H --> I["Acompanhar os pagamentos"]

    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. Defina o cálculo das parcelas

Existem duas formas de informar o valor:

Quando totalValue não puder ser dividido igualmente, a diferença será aplicada à última parcela.

2. Crie o parcelamento

Envie uma requisição para:

POST /v3/payments

Definindo o valor de cada parcela

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

Definindo o valor total

Substitua installmentValue por totalValue:

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

Consulte o endpoint: Criar nova cobrança.

Você também pode incluir desconto, juros e multa conforme a forma de pagamento utilizada. Consulte a referência para verificar os campos e regras disponíveis.

Resultado esperado

Em caso de sucesso, a API retornará a primeira cobrança gerada.

Armazene:

• id: identificador da cobrança retornada;
• installment: identificador do parcelamento;
• installmentNumber: número da parcela;
• status: situação atual da cobrança.

3. Recupere todas as parcelas

Utilize o ID retornado no campo installment:

GET /v3/installments/{id}/payments

Exemplo:

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

Consulte o endpoint: Listar cobranças de um parcelamento.

Cada parcela possui seu próprio:

• ID de cobrança;
• vencimento;
• valor;
• número;
• status.

Armazene esses identificadores para acompanhar e conciliar cada cobrança individualmente.

Parcelamento no cartão de crédito

Os limites de parcelamento são:

• até 21 parcelas para cartões Visa e Mastercard;
• até 12 parcelas para as demais bandeiras.

Consulte Cobranças via cartão de crédito para conhecer o envio dos dados do cartão ou do creditCardToken.

Acompanhe os pagamentos

Cada parcela possui seu próprio ciclo de vida.

Configure Webhooks para acompanhar mudanças de status, pagamentos, vencimentos e estornos.

Consulte:

• Configure Webhooks
• Eventos para cobranças

Erros comuns

Caso o parcelamento não seja criado, verifique se:

• installmentCount possui duas ou mais parcelas;
• foi enviado installmentValue ou totalValue;
• os dois campos de valor não foram enviados simultaneamente;
• o cliente pertence à mesma conta;
• a data de vencimento está no formato esperado;
• o limite da bandeira do cartão foi respeitado;
• o ID usado na listagem pertence ao parcelamento, e não a uma cobrança individual.

Próximos passos

• Consulte o endpoint: Criar nova cobrança
• Liste as cobranças de um parcelamento
• Recupere um parcelamento
• Gere o carnê do parcelamento
• Crie cobranças via boleto
• Crie cobranças via cartão de crédito
• Entenda os estornos