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

# Infoprodutos e cursos online

> Venda de cursos e produtos digitais com Pix e cartão parcelado, liberação de acesso só depois do pagamento confirmado, reembolso, disputas e coprodução com split.

Quem vende curso online, e-book, mentoria gravada ou comunidade paga entrega o produto no instante em que libera o acesso. Por isso, o ponto central da integração é liberar **só depois que o pagamento estiver confirmado**, e revogar quando houver reembolso ou contestação. Esta página mostra esse fluxo e, nas variações, como dividir a receita com coprodutores e afiliados.

> [!TIP]
>
> Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em [Integrar com IA](https://docs.fastpaybrasil.com/integrar-com-ia.md).

Implementar este caso com um assistente de IA

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md)
* [https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
* [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md)
* [https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)
* [https://docs.fastpaybrasil.com/guias/cobrancas/pix.md](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md)
* [https://docs.fastpaybrasil.com/guias/estorno.md](https://docs.fastpaybrasil.com/guias/estorno.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/split.md](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar neste projeto o fluxo descrito na página "Infoprodutos e cursos online" ([https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md](https://docs.fastpaybrasil.com/casos-de-uso/infoprodutos.md)). Resumo do caso: Venda de cursos e produtos digitais com Pix e cartão parcelado, liberação de acesso só depois do pagamento confirmado, reembolso, disputas e coprodução com split.

Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

## O cenário

A **Planilha Pro Educação** vende cursos de Excel e análise de dados para profissionais de escritório. O carro-chefe é o curso **Excel do Zero ao Dashboard**, por R\$ 497,00, em até 12x no cartão ou à vista no Pix. Em lançamentos, ela recebe até 1.200 pedidos em uma semana.

O que a Planilha Pro precisa:

* Pix com prazo de 1 hora, para o aluno pagar no app do banco sem pressa e sem deixar pedidos abertos por dias.
* Cartão parcelado em até 12x.
* Acesso à plataforma de aulas liberado só com pagamento confirmado.
* Reembolso por API quando o aluno pede dentro do prazo de garantia da escola.
* Em alguns cursos, divisão da receita com um professor coprodutor.

## O que a Finvia resolve

> [!NOTE]
>
> **Para o negócio:** a cobrança é criada com itens do tipo `digital`, sem endereço de entrega. No cartão, o resultado volta na resposta. No Pix, a confirmação chega por webhook (`charge.paid`). A Planilha Pro libera o acesso quando recebe esse evento **e** confirma o status consultando a cobrança na API, porque os webhooks não têm assinatura criptográfica. O reembolso é um estorno total feito por API. Com o Connect, a receita de um curso pode ser dividida com coprodutores e afiliados no momento da venda.

## Arquitetura da solução

| Necessidade | Recurso | Rota ou guia |
| - | - | - |
| Venda à vista instantânea | Cobrança Pix com `expirationInSeconds` | `POST /v1/charges` · [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) |
| Parcelamento | Cartão com `installments` até `12` | `POST /v1/charges` · [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) |
| Produto digital | `items[].type` `digital` | `POST /v1/charges` |
| Liberação de acesso | Webhook `charge.paid` e consulta da cobrança | [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) · `GET /v1/charges/{id}` |
| Reembolso | Estorno total | `POST /v1/refunds` · [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md) |
| Contestação | Bloqueio por chargeback ou MED | [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) |
| Coprodução e afiliados | Connect e `split` | [Split](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) |

O desenho abaixo mostra a venda de um curso da Planilha Pro, do checkout à liberação do acesso.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%

flowchart TB
    C(["Aluno"]):::comprador
    F["Checkout da Planilha Pro<br/>itens digital, sem endereço"]:::lojista
    S["Servidor da escola<br/>chave secreta sk_"]:::lojista
    API["Finvia API"]:::finvia
    ADQ["Adquirente e bandeiras<br/>cartão em até 12x"]:::externo
    PIX["Sistema Pix<br/>banco do aluno"]:::externo
    EV[["Eventos charge.*<br/>paid · refunded · blocked"]]:::evento
    COP(["Coprodutor<br/>subconta, opcional"]):::comprador
    W["Receptor de webhooks<br/>endpoint e postbackUrl"]:::lojista
    PL["Plataforma de aulas"]:::lojista
    OK(["Acesso liberado"]):::ok
    C -->|"1. compra o curso<br/>de R$ 497"| F
    F -->|"2. envia o pedido"| S
    S ==>|"3. POST /v1/charges<br/>pix · credit_card"| API
    API -.->|"4. 201 com o status<br/>ou o QR Code"| S
    API -->|"5a. autoriza o cartão"| ADQ
    API -->|"5b. Pix válido por 1 hora"| PIX
    API -->|"6. publica o evento"| EV
    API -.->|"split, se houver<br/>coprodução"| COP
    EV -.->|"7. entrega"| W
    W -->|"8. confere com<br/>GET /v1/charges/{id}"| PL
    PL ==>|"9. só com paid"| OK
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

A linha pontilhada da coprodução só existe quando a escola usa o Connect, como na variação do fim da página.

A liberação e a revogação do acesso seguem as regras do desenho abaixo.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%

flowchart TB
    EV[["charge.paid chega<br/>ao receptor"]]:::evento
    CARD(["Cartão: a resposta<br/>da criação veio paid"]):::neutro
    GET["GET /v1/charges/{id}<br/>confere o status real"]:::lojista
    Q{"Status<br/>na API?"}:::decisao
    ESP["Ainda não pago<br/>não libera o acesso"]:::alerta
    LIB["paid<br/>acesso liberado"]:::ok
    REF["refunded<br/>acesso revogado"]:::neutro
    BLK["Em disputa<br/>acesso suspenso"]:::alerta
    CB["chargeback<br/>revoga e registra a perda"]:::erro
    EV --> GET
    GET --> Q
    Q ==>|"paid"| LIB
    Q -->|"outro status"| ESP
    CARD ==> LIB
    LIB -->|"reembolso na garantia<br/>POST /v1/refunds"| REF
    LIB -->|"contestação<br/>charge.blocked ou<br/>charge.pre_chargeback"| BLK
    BLK -.->|"bloqueio liberado<br/>consulte isBlocked"| LIB
    BLK -->|"alerta devolvido<br/>charge.refunded"| REF
    BLK -->|"formalizado<br/>charge.updated"| CB
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

## Passo a passo

**1. Monte os itens do pedido**

Os cursos vão como itens `"type": "digital"`, e a cobrança não leva endereço de entrega. Se a Planilha Pro vender também uma apostila impressa, basta um item `physical` no pedido para o `shippingAddress` passar a ser obrigatório. Sem ele, a API responde `400` com `Shipping info must be provided for merchants selling physical items.`.

**2. Crie a cobrança Pix**

O aluno escolhe Pix. A cobrança vale 1 hora (`3600` segundos).

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 497,
    "currency": "BRL",
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "phone": "+5511987654321",
      "address": { "country": "BRA" }
    },
    "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 },
    "items": [
      {
        "title": "Excel do Zero ao Dashboard",
        "type": "digital",
        "description": "Acesso ao curso por 12 meses",
        "unit_price": 497,
        "quantity": 1
      }
    ],
    "metadata": { "pedido": "PP-20931", "curso": "excel-zero-dashboard" },
    "postbackUrl": "https://planilhapro.exemplo.com.br/webhooks/finvia"
  }'
```

A resposta traz `status` `pending` e o QR Code em `paymentDetails`. Mostre a imagem de `qrCodeBase64` e um botão para copiar o `copyPaste`, que é o que o aluno usa quando está comprando pelo próprio celular.

**3. Ou crie a cobrança no cartão parcelado**

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 497,
    "currency": "BRL",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "ipAddress": "177.128.144.97"
    },
    "paymentMethod": {
      "type": "credit_card",
      "number": "1111222233334444",
      "holderName": "MARIA SOUZA",
      "expirationMonth": "10",
      "expirationYear": "2028",
      "cvv": "123",
      "installments": 12
    },
    "items": [
      {
        "title": "Excel do Zero ao Dashboard",
        "type": "digital",
        "description": "Acesso ao curso por 12 meses",
        "unit_price": 497,
        "quantity": 1
      }
    ],
    "metadata": { "pedido": "PP-20932", "curso": "excel-zero-dashboard" },
    "postbackUrl": "https://planilhapro.exemplo.com.br/webhooks/finvia"
  }'
```

Com `status` `paid`, o pagamento foi aprovado. Com `refused` ou `failed`, o motivo vem em `reason` e a página de checkout oferece o Pix ou outro cartão. Com `in_analysis`, a cobrança foi para revisão manual do antifraude: não libere o acesso e aguarde o desfecho.

**4. Libere o acesso só com pagamento confirmado**

A regra da Planilha Pro é: **nenhum acesso é liberado sem `status` `paid` confirmado pela API**. O webhook é o gatilho, e a consulta é a confirmação.

```javascript theme={null}
app.post('/webhooks/finvia', async (req, res) => {
  const { id, event, data } = req.body;
  if (id && (await eventos.jaProcessado(id))) return res.status(200).send('OK');
  res.status(200).send('OK');

  if (event === 'charge.paid') {
    const cobranca = await finvia.get(`/v1/charges/${data.id}`);
    if (cobranca.status === 'paid') {
      await plataformaDeAulas.liberarAcesso(cobranca.metadata.pedido);
    }
  }
  if (event === 'charge.refunded') {
    const cobranca = await finvia.get(`/v1/charges/${data.id}`);
    if (cobranca.status === 'refunded') {
      await plataformaDeAulas.revogarAcesso(cobranca.metadata.pedido);
    }
  }
  if (id) await eventos.marcarProcessado(id);
});
```

> [!TIP]
>
> **Para o desenvolvedor:** no cartão, a resposta da criação já traz `paid`. Você pode liberar o acesso a partir dela, porque ela vem da chamada que o seu servidor fez à API. O que não deve liberar acesso sozinho é um POST recebido no endpoint de webhook sem confirmação: qualquer um que descubra a URL pode enviar um payload falso.

O mesmo evento pode chegar mais de uma vez. Guarde os `id` de evento já processados em banco de dados ou cache persistente, que sobrevivem a uma reinicialização do servidor.

**5. Reembolse dentro da garantia**

A Planilha Pro oferece garantia de 7 dias. Quando o aluno pede o reembolso, o sistema verifica o prazo pela política da escola e pede o estorno total:

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/refunds" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "chargeId": "2vorkDcXyvzifL63YX09S9VqcnI",
    "reason": "Pedido de reembolso dentro da garantia, pedido PP-20931"
  }'
```

| Resposta | O que fazer |
| - | - |
| `status` `refunded` | Revogar o acesso e confirmar ao aluno |
| `422` "Já existe um reembolso para esta cobrança" | O estorno já foi pedido: não reenvie |
| `404` "Cobrança não encontrada" | A cobrança não está `paid` (por exemplo, já estornada ou em chargeback). Consulte a cobrança antes de agir |

A API faz só estorno total, e cada cobrança aceita um único estorno. Se a chamada der timeout, consulte a cobrança antes de reenviar: se ela já estiver `refunded`, não peça de novo. No Pix, a devolução é enviada na hora para a conta de origem do aluno; peça o estorno em até 90 dias do pagamento, que é o prazo das regras do Pix. No cartão, o crédito aparece na fatura conforme o prazo do banco emissor.

**6. Acompanhe contestações**

Se o aluno contestar a compra no banco (chargeback no cartão ou MED, o Mecanismo Especial de Devolução, no Pix), a equipe Finvia bloqueia a cobrança. Ela continua `paid`, passa a ter `isBlocked: true`, e o evento `charge.blocked` chega aos endpoints e ao `postbackUrl`. A Planilha Pro suspende o acesso enquanto a disputa corre e guarda as evidências da venda: registro de acesso às aulas, e-mail de compra, aceite dos termos. O alerta chega por e-mail à conta, e a Planilha Pro envia essas evidências em resposta a esse e-mail, dentro do prazo indicado nele. Não existe rota de API para defesa.

| Aviso | O que a Planilha Pro faz |
| - | - |
| `charge.blocked` | Suspende o acesso |
| `charge.pre_chargeback` | Alerta de pré-chargeback: suspende o acesso |
| `charge.refunded` com `chargeback_alert_refunded: true` | O valor já foi devolvido no alerta: trata como reembolsado e revoga o acesso |
| `charge.updated` com `status: "chargeback"` (só no `postbackUrl`) | Chargeback formalizado: revoga o acesso e registra a perda |

A liberação do bloqueio não gera aviso: consulte `isBlocked` em `GET /v1/charges/{id}` para saber se o acesso pode voltar. O fluxo completo está em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

## Regras e cuidados

> [!WARNING]
>
> **Não libere acesso a partir do webhook sem consultar a API.** Os webhooks não têm assinatura HMAC ([Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#regras-de-negócio)): confirme o status com `GET /v1/charges/{id}` antes de entregar o produto.

> [!WARNING]
>
> **Valor em reais.** `"amount": 497` é R\$ 497,00. Enviar `49700` gera uma cobrança de R\$ 49.700,00.

* **Pix mínimo de 15 minutos.** `expirationInSeconds` aceita a partir de `900`. Para prazos em dias, use `expirationInDays` (mínimo `1`).
* **Sem endereço em produto digital.** `shippingAddress` é para produto físico. Em cobrança só com itens `digital`, não envie.
* **Postback em toda cobrança.** O `charge.updated` com `status: "chargeback"` e os avisos de recusa informada depois pela adquirente chegam só pelo `postbackUrl`.
* **Prazo de garantia é da sua política.** A API não impõe prazo máximo para pedir o estorno (no Pix, peça em até 90 dias do pagamento, pelas regras do Pix). Quem decide se o pedido está dentro da garantia é o seu sistema.

> [!NOTE]
>
> Os formatos dos avisos são diferentes. No envelope padrão (`charge.paid`, `charge.refunded` e os demais), as chaves do primeiro nível de `data` vêm em snake\_case (`psp_ref_id`, `merchant_id`) e o `metadata` volta como foi enviado. O `charge.updated` e as respostas da API usam camelCase, inclusive nas chaves de `metadata`. Por isso, os exemplos usam chaves de `metadata` de uma palavra só (`pedido`, `curso`), que ficam iguais em todos os formatos.

## Variações do caso

> [accordion] E se o curso tiver um professor coprodutor?
>
> A divisão automática exige o Connect. A Planilha Pro passa a ser a conta master e o coprodutor, uma subconta do mesmo grupo, com cadastro e KYC próprios. Na venda criada pela conta master, o `split` manda a parte do coprodutor para a subconta dele:
>
> ```json theme={null}
> {
>   "amount": 497,
>   "currency": "BRL",
>   "customer": { "name": "Joao Silva", "email": "joao@email.com" },
>   "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 },
>   "items": [
>     { "title": "Power BI na Prática", "type": "digital", "description": "Curso em coprodução", "unit_price": 497, "quantity": 1 }
>   ],
>   "split": [
>     { "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI", "percentage": 40 }
>   ],
>   "postbackUrl": "https://planilhapro.exemplo.com.br/webhooks/finvia"
> }
> ```
>
> O percentual incide sobre o **valor líquido**: o valor da venda menos a taxa transacional da Finvia. Se o acordo de coprodução já é sobre o líquido ("40% do que entrar"), informe `40`. Se o acordo é sobre o bruto, ajuste o percentual com a fórmula de [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md). Se a Planilha Pro antecipar o recebível, o split é recalculado sobre o valor já descontada a taxa de antecipação.
>
> A parte do coprodutor é repassada quando o recebível da Planilha Pro é liquidado: no Pix, logo após a confirmação do pagamento; no cartão, parcela a parcela, em D+30, D+60 e assim por diante. Os eventos da cobrança vão só para a Planilha Pro, dona da venda; a subconta do coprodutor não recebe esses avisos.

> [accordion] E se houver afiliados?
>
> Cada afiliado vira uma subconta no grupo da escola. Na venda indicada por um afiliado, a cobrança leva um segundo item no `split`, com a subconta do afiliado e o percentual combinado. A soma de todos os percentuais não pode passar de 100%, e o que sobra fica com quem originou a venda. Como o afiliado só recebe por subconta ativa, inclua o cadastro e o KYC dele no processo de entrada no programa.

> [accordion] E se a escola quiser vender o curso por assinatura mensal?
>
> Use as assinaturas, que cobram o cartão automaticamente a cada ciclo. O desenho, com liberação e bloqueio de acesso por `subscription.*`, está em [SaaS por assinatura](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md). As cobranças recorrentes das assinaturas não recebem split, então um curso em coprodução vendido por assinatura não divide a receita automaticamente.

> [accordion] E se o aluno quiser comprar o segundo curso sem digitar o cartão de novo?
>
> Registre o cartão no cofre com `POST /v1/cards` (cliente com e-mail e CPF) e use `cardTokenId` na próxima compra. O CVV continua obrigatório a cada cobrança. Veja [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md).

## Checklist de implementação

* [ ] Itens enviados com `"type": "digital"` e sem `shippingAddress`; com item `physical`, endereço completo
* [ ] Pix com validade definida (a partir de `900` segundos)
* [ ] Cartão com `installments` até `12`
* [ ] Liberação de acesso só com `status` `paid` confirmado em `GET /v1/charges/{id}`
* [ ] Idempotência persistente pelo `id` do evento
* [ ] Suspensão de acesso em `charge.blocked` e `charge.pre_chargeback`, e revogação em `charge.refunded` e no `charge.updated` com `chargeback`
* [ ] Estorno com checagem prévia para não duplicar
* [ ] `postbackUrl` em toda cobrança
* [ ] Para coprodução e afiliados: Connect habilitado, subcontas ativas e percentuais somando até 100%

## Como homologar

| Funcionalidade | Cenários |
| - | - |
| Pix e cartão | CHG-01, CHG-02, CHG-03, CHG-04 e CHG-05 |
| Consulta, estorno e webhooks | CHG-06, CHG-07, CHG-08 e CHG-09 |
| Coprodução e afiliados | FC-01 a FC-06 e SPL-01 a SPL-06 |

No Modo Teste, o Pix passa sozinho para `paid` cerca de 5 segundos depois da criação (CHG-05), e o cartão `4444333322221112` gera a recusa do CHG-03. Use o reenvio de webhook de teste (CHG-09, `POST /v1/charges/{id}/resend-webhook`) para testar o tratamento de outros status: ele dispara um evento novo, com `id` novo, e não altera a cobrança. Como a consulta `GET /v1/charges/{id}` continua mostrando o status real, a liberação de acesso só acontece com um pagamento confirmado. Detalhes no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

## Veja também

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos, envelopes e retentativas.

> [card] [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md)
>
> Estorno total e o que acontece com a cobrança.

> [card] [Split](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
>
> Como dividir uma venda entre contas do mesmo grupo.

> [card] [Reenviar webhook de teste](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste.md)
>
> Simule eventos no sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.