Skip to main content
Ao criar um checkout, você pode definir o número máximo de parcelas que o cliente pode escolher no cartão de crédito. O cliente seleciona as parcelas na tela de pagamento e o valor total é dividido automaticamente.

Não disponível em assinaturas

Parcelamento funciona em checkouts ONE_TIME e links de pagamento (MULTIPLE_PAYMENTS). Apenas assinaturas (SUBSCRIPTION) não suportam parcelamento.

​
Como funciona

Envie o objeto card com o campo maxInstallments ao criar o checkout. O valor deve ser um inteiro entre 1 e 12. 
POST /checkouts/create
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "methods": ["CARD"],
  "card": {
    "maxInstallments": 12
  }
}
O checkout gerado exibe um seletor para o cliente escolher de 1x até o máximo definido.

​
Regras e restrições

RegraDetalhe
Mínimo por parcelaR10,00—paraoferecer3xototaldeveser≥R 10,00 — para oferecer 3x o total deve ser ≥ R 30,00
Máximo de parcelas12x
Método obrigatórioCARD deve estar em methods
FrequênciaONE_TIME e MULTIPLE_PAYMENTS; não funciona em assinaturas (SUBSCRIPTION)
Se o valor total for insuficiente para o número de parcelas configurado, a API retorna erro: "Total below minimum for Nx (R$10 per installment)".

​
Exemplo completo

POST /checkouts/create
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "customerId": "cust_abc123xyz",
  "externalId": "pedido-456",
  "returnUrl": "https://seusite.com/voltar",
  "completionUrl": "https://seusite.com/sucesso",
  "methods": ["PIX", "CARD"],
  "card": {
    "maxInstallments": 6
  }
}
Resposta: 
{
  "data": {
    "id": "bill_abc123xyz",
    "url": "https://app.abacatepay.com/pay/bill_abc123xyz",
    "amount": 10000,
    "status": "PENDING",
    "frequency": "ONE_TIME",
    "methods": ["PIX", "CARD"],
    "card": {
      "maxInstallments": 6
    },
    "createdAt": "2025-04-17T12:00:00.000Z",
    "updatedAt": "2025-04-17T12:00:00.000Z"
  },
  "success": true,
  "error": null
}
Use a url retornada para levar o cliente ao checkout. O seletor de parcelas aparece automaticamente na tela de pagamento quando maxInstallments for maior que 1.

​
Só aceitar cartão parcelado

Se o seu produto só faz sentido com parcelamento (ex: curso, produto de ticket alto), remova o PIX de methods e defina maxInstallments: 
{
  "items": [{ "id": "prod_abc123xyz", "quantity": 1 }],
  "methods": ["CARD"],
  "card": {
    "maxInstallments": 12
  }
}

​
Próximos passos

Criar checkout

Veja todos os campos disponíveis ao criar um checkout.

Webhooks

Receba notificações quando cada parcela for paga.