Receber parcelado (Cartão)

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

Regra	Detalhe
Mínimo por parcela	R $10,00 — para oferecer 3x o total deve ser ≥ R$ 30,00
Máximo de parcelas	12x
Método obrigatório	`CARD` deve estar em `methods`
Frequência	`ONE_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,
      "passFeesToCustomer": false
    },
    "customerFee": null,
    "installmentsCount": null,
    "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.

Confirmar as parcelas após o pagamento

Após o pagamento, o campo installmentsCount no objeto do checkout passa a refletir o número de parcelas escolhido pelo cliente. Para pagamentos à vista ou via outros métodos (PIX, Boleto) o valor é sempre null. Use GET /checkouts/get para consultar o checkout após receber o webhook checkout.completed:

{
  "data": {
    "id": "bill_abc123xyz",
    "status": "PAID",
    "methods": ["CARD"],
    "installmentsCount": 6,
    ...
  },
  "success": true,
  "error": null
}

Repassar a taxa ao cliente

Com card.passFeesToCustomer: true, o cliente paga a taxa do cartão e você recebe o preço cheio. Para o passo a passo, veja o guia Repassar a taxa do cartão ao cliente.

POST /checkouts/create
{
  "items": [
    { "id": "prod_abc123xyz", "quantity": 1 }
  ],
  "methods": ["PIX", "CARD"],
  "card": {
    "maxInstallments": 6,
    "passFeesToCustomer": true
  }
}

Em cada opção, de 1x até maxInstallments, o cliente paga o menor valor que, descontada a sua taxa, cobre o preço. Exemplo com uma taxa de 4% + R $0,60: num produto de R$ 100,00, o cliente paga R $104,79 e você recebe R$ 100,00.
O acréscimo muda com o número de parcelas, porque a taxa muda. O checkout mostra o total de cada opção antes do cliente pagar.
Só o cartão tem acréscimo. PIX, boleto, Apple Pay e Google Pay cobram o preço normal.
Com cupom, o acréscimo é calculado sobre o valor com desconto e o cartão sai à vista.
Vale para checkout avulso e link de pagamento. Assinatura não aceita.
No reembolso, o cliente recebe de volta tudo o que pagou, com o acréscimo. O valor sai do seu saldo, e a taxa do cartão não é devolvida, como em qualquer reembolso.

Depois do pagamento, o acréscimo vem em customerFee (em centavos) no GET /checkouts/get e no webhook checkout.completed. O amount do checkout continua sendo o preço; no webhook, amount traz o total que o cliente pagou.

Erro	Quando acontece
`card.passFeesToCustomer requires CARD in methods`	`CARD` não está em `methods`
`card.passFeesToCustomer is not available for subscriptions`	O checkout é uma assinatura
`card.passFeesToCustomer requires card payments through Rinne`	Sua conta ainda não está habilitada para o repasse. Fale com o suporte. Em dev mode, funciona em qualquer conta.

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
  }
}

Introdução

Cobrar com Checkout

Links de pagamento

Clientes

Portal do cliente

Checkout Transparente

Cupons

Produtos

Webhooks

Assinaturas

Saques

PIX

Extrato

Loja

Public MRR

Receber parcelado (Cartão)

Não disponível em assinaturas

Como funciona

Regras e restrições

Exemplo completo

Confirmar as parcelas após o pagamento

Repassar a taxa ao cliente

Só aceitar cartão parcelado

Próximos passos

Criar checkout

Webhooks

Não disponível em assinaturas

​Como funciona

​Regras e restrições

​Exemplo completo

​Confirmar as parcelas após o pagamento

​Repassar a taxa ao cliente

​Só aceitar cartão parcelado

​Próximos passos

Criar checkout

Webhooks

Como funciona

Regras e restrições

Exemplo completo

Confirmar as parcelas após o pagamento

Repassar a taxa ao cliente

Só aceitar cartão parcelado

Próximos passos