> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vender assinatura parcelada

> Divida no cartão a venda de ciclos maiores que mensais — anuidade em até 12x, com setup na primeira cobrança e renovação que conserva a condição sozinha.

Este guia vende **uma anuidade em 12x com taxa de setup** e chega à renovação
que se cobra sozinha, na mesma condição, sem novo aceite. O ponto central do
modelo: parcelar **não** transforma a assinatura em doze cobranças mensais. A
venda do ciclo é **uma única transação** pelo total (com os juros pagos pelo
comprador), o limite do cartão é comprometido pelo valor integral, e a
recorrência continua anual — o cartão salvo só volta a ser usado na próxima
renovação.

Quem guarda o quê:

| Objeto         | Papel no parcelamento                                                                       |
| -------------- | ------------------------------------------------------------------------------------------- |
| Subscription   | A condição **contratada** para as próximas faturas (`payment_settings`)                     |
| Invoice        | A condição **congelada** daquela cobrança — toda tentativa cobra exatamente o que está aqui |
| Payment Intent | A execução: total com juros, quantidade enviada ao cartão                                   |
| Charge         | O fato aprovado ou recusado                                                                 |

<Note>
  Como nos outros guias, tudo roda em **test mode** (`ch_test_...`), sem
  dinheiro real. Se esta é a sua primeira integração, faça antes o [Aceitar o
  primeiro pagamento](/accept-your-first-payment). Daqui em diante os exemplos
  mostram só o **payload**: o método e a rota ficam no título de cada bloco.
</Note>

## Quantas parcelas o plano comporta

Não existe configuração de parcelamento por produto ou por assinatura. Todo
preço recorrente com período **maior que um mês** oferece parcelas
automaticamente, e o máximo é o menor entre quatro limites:

```text theme={"theme":"css-variables"}
máximo = min(
  12,                          — limite do cartão
  máximo da organização,       — configurado nas opções de checkout
  meses do período,            — trimestral 3, semestral 6, anual 12
  ⌊valor recorrente ÷ R$ 7,00⌋ — cada parcela precisa de pelo menos R$ 7,00
)
```

O valor usado no último limite é **somente o recorrente com desconto** — o que
volta em toda renovação. Cobranças iniciais como setup entram no valor
parcelado da primeira fatura, mas nunca aumentam o máximo.

| Plano                               | Meses | Limite pelo valor | Máximo oferecido |
| ----------------------------------- | ----: | ----------------: | ---------------: |
| Anual de R\$ 419,80                 |    12 |               59x |          **12x** |
| Anual de R\$ 60,00                  |    12 |                8x |           **8x** |
| Anual de R$ 60,00 + setup R$ 120,00 |    12 |                8x |           **8x** |
| Semestral de R\$ 300,00             |     6 |               42x |           **6x** |
| Trimestral de R\$ 90,00             |     3 |               12x |           **3x** |
| Mensal (qualquer valor)             |     1 |                 — |               1x |

Quando o resultado é menor que 2, a venda é à vista e o objeto não carrega
plano de parcelamento (`payment_method_options: null`).

## 1. Modele o plano e o setup

O plano é um preço recorrente comum; o setup é um **preço avulso** de outro
produto — nunca um atributo do plano. É essa separação que impede o setup de
reaparecer nas renovações.

```json POST /v1/products theme={"theme":"css-variables"}
{
  "name": "Plano Pro",
  "prices": [
    {
      "currency": "brl",
      "recurring": {
        "interval": "year"
      },
      "type": "recurring",
      "unit_amount": 41980
    }
  ]
}
```

```json POST /v1/products theme={"theme":"css-variables"}
{
  "name": "Implantação assistida",
  "prices": [
    {
      "currency": "brl",
      "type": "one_time",
      "unit_amount": 12000
    }
  ]
}
```

## 2. Caminho hospedado: o comprador escolhe as parcelas

Crie uma Checkout Session com o plano e o setup no mesmo carrinho. O checkout
particiona sozinho: o recorrente vira a assinatura, o avulso entra **somente na
primeira fatura** — a página marca a linha com "Cobrado somente na primeira
fatura" e mostra o valor das próximas renovações à parte.

```json POST /v1/checkout-sessions theme={"theme":"css-variables"}
{
  "line_items": [
    {
      "price_id": "price_iq9QEr7E4sssospy",
      "quantity": 1
    },
    {
      "price_id": "price_mB4Tqw2cXV7pLdKe",
      "quantity": 1
    }
  ],
  "submit_type": "subscribe"
}
```

O seletor abre em **1x** — como os juros são do comprador, subir de parcela é
uma escolha dele — e lista cada opção com valor da parcela e total com juros.
Ao confirmar, uma única transação leva plano + setup na quantidade escolhida.

## 3. Caminho direto: transmita a escolha feita no seu checkout

Se o comprador escolheu as parcelas na sua própria interface, transmita a
condição na criação. Você não define uma política — apenas repassa o que o
comprador aceitou, e a Chargefy valida contra a regra única acima.

```json POST /v1/subscriptions theme={"theme":"css-variables"}
{
  "add_invoice_items": [
    {
      "price": "price_mB4Tqw2cXV7pLdKe"
    }
  ],
  "customer": "cus_QiCDEd21hLKBQKpM",
  "default_payment_method": "pm_fCsGveGEX26tvBcL",
  "items": [
    {
      "price": "price_iq9QEr7E4sssospy"
    }
  ],
  "payment_settings": {
    "payment_method_options": {
      "credit_card": {
        "installments": {
          "plan": {
            "count": 12,
            "interval": "month",
            "type": "fixed_count"
          }
        }
      }
    }
  }
}
```

A resposta conserva a condição contratada — e é o mesmo shape que os eventos
`subscription.*` carregam:

```json Resposta (recorte) theme={"theme":"css-variables"}
{
  "id": "sub_MHiXqfpe764KwFgX",
  "object": "subscription",
  "payment_settings": {
    "payment_method_options": {
      "credit_card": {
        "installments": {
          "plan": {
            "count": 12,
            "interval": "month",
            "type": "fixed_count"
          }
        }
      }
    }
  },
  "...": "demais campos da Subscription"
}
```

A primeira fatura nasce **congelada**: quantidade, juros e total ficam
gravados nela, e toda tentativa — automática, retentativa da régua ou página
hospedada da fatura — cobra exatamente esse valor. Nenhuma mudança posterior
na organização altera uma fatura já aberta.

```json GET /v1/invoices/in_hJgPKzC2vRq8sWmA (recorte) theme={"theme":"css-variables"}
{
  "id": "inv_e4z5bbjuCCGawjft",
  "object": "invoice",
  "amount_due": 53980,
  "payment_settings": {
    "payment_method_options": {
      "credit_card": {
        "installments": {
          "plan": {
            "count": 12,
            "interval": "month",
            "type": "fixed_count"
          }
        }
      }
    }
  },
  "...": "demais campos da Invoice"
}
```

<Info>
  `amount_due` é o principal — o que quita a fatura e baseia a taxa da
  Chargefy e, quando houver, a taxa da plataforma. Os juros do parcelamento
  aparecem no Payment Intent e na Charge
  (`installment_interest_amount`), somados ao total enviado ao cartão.
</Info>

## 4. Com trial: plano e setup esperam juntos

Num plano com trial, a escolha de parcelas acontece na confirmação e o cartão
é salvo, mas **nada é cobrado no início** — nem o setup. A primeira fatura
pagável, no fim do trial, cobra plano e setup juntos, na quantidade escolhida.
Se a assinatura for cancelada antes disso, o setup pendente é descartado e
nunca pode ser capturado por uma fatura posterior.

## 5. Renovação: a condição se conserva sozinha

A cada ciclo, a renovação cria uma nova fatura, congela a mesma quantidade com
a taxa contratada na venda e cobra o cartão salvo em **uma nova transação
integral**. Não há novo aceite nem recálculo: se a organização mudar o máximo
de parcelas depois, as assinaturas já contratadas não mudam. O setup não
retorna — só as linhas recorrentes.

Fique em `invoice.paid` e `invoice.payment_failed` para reagir aos ciclos; a
[régua de retentativas](/payments/create-subscriptions) segue a mesma dos
outros planos, sempre sobre o valor congelado.

## Quando a criação é recusada

Erros de validação chegam com `error.code` estável e `error.param` apontando o
campo — trate pelo code, nunca pela mensagem:

| `error.code`                                 | Causa e correção                                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `installment_count_exceeds_maximum`          | O `count` passa da regra efetiva; a mensagem informa o teto. Ofereça no máximo esse valor.             |
| `subscription_installments_not_supported`    | Plano mensal ou mais curto, item medido, ou cobrança por fatura. Envie a assinatura à vista.           |
| `invoice_item_price_must_be_one_time`        | `add_invoice_items` recebeu um preço recorrente. Use um preço avulso (`type: one_time`).               |
| `parameter_unknown`                          | Campo fora da allowlist de `payment_settings` — nada é ignorado em silêncio. Remova o campo apontado.  |
| `subscription_interval_change_not_supported` | Tentativa de trocar a cadência de uma assinatura existente. Crie outra assinatura ao término da atual. |

Duas regras de atualização valem para sempre: `payment_settings` é **somente
leitura** depois da criação, e uma mudança de itens que deixaria o valor
recorrente abaixo de R\$ 7,00 por parcela contratada é recusada antes de entrar
em vigor.

## Teste antes de ligar

Em test mode, os [cartões determinísticos](/test-payments-in-sandbox) valem
para o fluxo inteiro: aprove a primeira venda em 12x com `4242 4242 4242
4242`, force uma recusa com `4000 0000 0000 9995` e confirme que a retentativa
cobra o mesmo total congelado. O caminho completo — criação, fatura congelada,
recusa, retentativa e renovação — se comporta exatamente como em produção.