> ## 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.

# Roteiro de homologação

> Cenários de teste por funcionalidade, o resultado esperado de cada um e as evidências que a equipe Finvia confere antes da virada para produção.

A homologação é a etapa em que você executa no ambiente de testes (sandbox) os cenários das funcionalidades que integrou e guarda as evidências de cada um. Ela é recomendada antes de virar para produção e é acompanhada pela equipe Finvia: fale com o suporte da Finvia para agendar a homologação e enviar as evidências.

A API não tem uma trava técnica de homologação. A chave de produção pode ser gerada no painel assim que a conta é aprovada, e as subcontas já nascem com credenciais. Mesmo assim, executar este roteiro é a forma de comprovar que a integração trata os caminhos de sucesso e de erro antes de receber clientes reais.

Este roteiro diz **o que testar e o que comprovar**. O passo a passo técnico de cada recurso está nos guias e na referência da API, indicados em cada seção.

> [!NOTE]
>
> **Para o negócio:** na homologação, a integração prova que trata pagamento aprovado, recusado e estornado, webhook recebido e valor em reais. Um cenário que falha aponta um problema que apareceria com clientes reais. Corrija antes de virar.

## Como usar

O desenho abaixo mostra a jornada da homologação, da chave de teste até a liberação para o go-live.

```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
    K(["Gere a chave de teste<br/>com Owner ou Manager"]):::lojista
    Q{"O que você<br/>integrou?"}:::decisao
    A["A · Cobrança<br/>CHG-01 a 10"]:::neutro
    B["B · Split<br/>SPL-01 a 06"]:::neutro
    C["C · Connect<br/>FC-01 a 08"]:::neutro
    D["D · Apple Pay<br/>AP-01 a 06"]:::neutro
    E["E · Saques<br/>PAY-01 a 07"]:::alerta
    F["F · Cartão salvo<br/>e assinaturas<br/>SUB-01 a 06"]:::alerta
    EV["Guarde as evidências<br/>requisição, resposta, id<br/>e webhook com 2xx"]:::lojista
    SUP["Envie ao suporte<br/>uma linha por cenário"]:::lojista
    FIN{"A equipe Finvia<br/>aponta problema?"}:::decisao
    FIX["Corrija a integração<br/>e envie nova evidência"]:::erro
    GO(["Siga para o<br/>checklist de go-live"]):::ok
    K --> Q
    Q --> A
    Q --> B
    Q --> C
    Q --> D
    Q --> E
    Q --> F
    A --> EV
    B --> EV
    C --> EV
    D --> EV
    E --> EV
    F --> EV
    EV --> SUP --> FIN
    FIN -->|"sim"| FIX
    FIX --> SUP
    FIN -->|"não"| GO
    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 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
```

Os cenários de saques (E) são uma conferência de contrato, porque não existe saque no Modo Teste. Os de assinatura (F) usam cartão real: cancele a assinatura no mesmo dia.

**1. Gere a chave de teste**

No painel, em **Configurações > Chave de API**, abra a aba **Teste** e gere o par `sk_test_`/`pk_test_`. Gere com um usuário Owner ou Manager: uma chave gerada por Desenvolvedor recebe `403` ao criar cobranças. Veja [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#onde-obter-as-chaves).

**2. Escolha as seções que se aplicam**

Execute os cenários das funcionalidades que você integrou: **Cobrança sem split**, **Cobrança com split**, **Connect (subcontas)**, **Apple Pay**, **Saques (payout)** e/ou **Cartão salvo e assinaturas**.

**3. Guarde as evidências de cada cenário**

Para cada cenário, guarde: **corpo da requisição**, **corpo da resposta**, o **ID gerado** (cobrança, subconta ou saque) e, quando houver, o **registro do webhook recebido** e a **resposta HTTP que o seu endpoint devolveu**.

**4. Envie as evidências ao suporte**

Fale com o suporte da Finvia para agendar a homologação e enviar as evidências, organizadas por código de cenário. Veja a seção [Envio das evidências](#envio-das-evidências), no fim desta página.

## Convenções de evidência

| Tipo | O que enviar | Por que |
| - | - | - |
| Requisição e resposta | JSON completo. Pode omitir dados de cartão: a Finvia não precisa do número do cartão (PAN) | Mostra que o corpo respeita o contrato e que a resposta foi tratada |
| Webhook | Print ou log com o evento recebido e o **status `2xx`** que o seu endpoint respondeu | Prova que o endpoint recebe e confirma a entrega. Qualquer resposta fora de `2xx` conta como falha |
| Identificadores | Sempre o `id` da cobrança, subconta ou saque | Permite à equipe Finvia rastrear o cenário nos registros dela |
| Critério | Um cenário só é considerado **testado** com a evidência anexada | "Funcionou" sem evidência não comprova o cenário |

> [!TIP]
>
> **Para o desenvolvedor:** registre requisição, resposta e webhooks em log desde o primeiro teste, com o `id` de cada objeto. Montar a evidência no fim, a partir do log, é mais rápido do que refazer cenários. Mascare dados de cartão e chaves antes de enviar.

### Cartões de teste

No Modo Teste, o resultado da cobrança de cartão depende só do número. Envie só dígitos, sem espaços.

| Número | Resultado | `status` / `reason` |
| - | - | - |
| `4444333322221111` | Aprovado | `paid` / `success` |
| `4444333322221112` | Recusado | `refused` / `card_declined` |
| Qualquer número terminado em `2222` | Pendente, sem confirmação posterior | `pending` / `pending` |
| Qualquer outro número | Aprovado | `paid` / `success` |

Nome, CVV e validade não mudam o resultado (use validade futura, com mês de 2 dígitos, ex.: `05`, e ano com 4, e CVV de 3 dígitos). As regras de 3D Secure e de antifraude da conta continuam valendo no Modo Teste. Para os cenários de recusa, use uma conta sem 3DS obrigatório; do contrário, a recusa pode vir dessas etapas, com outro `reason`.

## A. Cobrança sem split (cartão de crédito e Pix)

Cenários para quem cria cobranças Pix ou de cartão de crédito.

Referências: [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) · [Consultar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md) · [Estornar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/estornar.md) · [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)

| Código | Cenário | Resultado esperado | Evidência a enviar |
| - | - | - | - |
| CHG-01 | Cobrança de cartão de crédito **aprovada à vista** (1x), com o cartão `4444333322221111` | Cobrança criada com status `paid`; webhook `charge.paid` recebido | Requisição + resposta + `id` + registro do webhook |
| CHG-02 | Cobrança de cartão **parcelada** (ex.: 3x), com o cartão `4444333322221111` | Status `paid`; `installments` refletido | Requisição + resposta + `id` |
| CHG-03 | Cobrança de cartão **recusada**, com o cartão `4444333322221112` | Status `refused` e `reason` `card_declined` **na própria resposta**; webhook `charge.refused` (ou `charge.failed`, se o status for `failed`) | Requisição + resposta mostrando `refused` e o motivo + registro do webhook |
| CHG-04 | **Pix gerado** | Status `pending`; resposta traz copia e cola e QR Code; webhooks `charge.created` e `charge.pending` | Requisição + resposta (com copia e cola) + `id` + webhook |
| CHG-05 | **Pix pago** no sandbox | Cerca de 5 segundos depois da criação, a cobrança passa sozinha para `paid`; webhook `charge.paid` | Registro do webhook `charge.paid` com o mesmo `id` retornado na criação |
| CHG-06 | **Consulta** da cobrança (`GET /v1/charges/{id}`) | Retorna o status atual e os detalhes de pagamento | Resposta do GET |
| CHG-07 | **Estorno total** de uma cobrança paga (use a do CHG-01 ou a do CHG-05) | Status `refunded`; webhook `charge.refunded` | Requisição de estorno + resposta + webhook |
| CHG-08 | **Recebimento de webhook** | Seu endpoint recebe o evento e responde **`2xx`** em poucos segundos | Print/log do webhook recebido + status respondido |
| CHG-09 | **Simulação de webhook (sandbox)** | Resposta `201` com `deliveries`; evento simulado recebido pelo seu endpoint | Resposta da simulação + log do evento recebido ([simular webhook](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste.md)) |
| CHG-10 | **Item físico com endereço de entrega** | Sem `shippingAddress`, a API responde `400` com `Shipping info must be provided for merchants selling physical items.`; com o endereço, `201` | As duas requisições e respostas |

> [!NOTE]
>
> Autenticação obrigatória em todos os cenários. O 3D Secure, quando aplicável à sua conta, é coberto pelos guias de [3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md).

### Por que cada cenário existe e como executar

> [accordion] CHG-01 e CHG-02: aprovação à vista e parcelada
>
> Comprovam que o corpo da cobrança de cartão está completo (`number`, `holderName`, `expirationMonth`, `expirationYear` com 4 dígitos, `cvv`, `installments`) e que o seu sistema lê o `status` da resposta. O CHG-02 confirma que o parcelamento chega à cobrança: envie `installments` maior que 1 (de `1` a `12`) e mostre o valor refletido em `paymentDetails.installments`.
>
> **Rota:** `POST /v1/charges` com `paymentMethod.type` `credit_card` e o cartão `4444333322221111`. **Dica:** envie `amount` em reais (`10` = R\$ 10,00) e `postbackUrl` para já capturar o `charge.paid` do CHG-01. O parcelamento só funciona se a conta tiver taxa configurada para o número de parcelas; sem ela, a resposta é `422` com `Fees not configured`.

> [accordion] CHG-03: recusa
>
> Comprova que o checkout trata a recusa a partir da resposta, mostrando uma mensagem ao comprador e oferecendo outra forma de pagamento. Use o cartão `4444333322221112`, em uma conta sem 3D Secure obrigatório.
>
> **Rota:** `POST /v1/charges`. A recusa vem na resposta síncrona e também no webhook `charge.refused` (status `refused`) ou `charge.failed` (status `failed`), enviado aos endpoints e à `postbackUrl`, no máximo uma vez por cobrança. **Dica:** trate a recusa pela resposta. O webhook é complementar e não traz o motivo; o motivo está em `reason`.

> [accordion] CHG-04 e CHG-05: Pix gerado e pago
>
> O CHG-04 comprova que o seu sistema exibe o código copia e cola (`paymentDetails.copyPaste`) e o QR Code (`qrCodeBase64`, que pode vir `null`). O CHG-05 comprova que o pedido muda para pago quando chega o `charge.paid` com o mesmo `id`.
>
> **Rota:** `POST /v1/charges` com `paymentMethod.type` `pix` e `expirationInDays` (mínimo `1`) ou `expirationInSeconds` (mínimo `900`). No Modo Teste, o código Pix é fictício e não deve ser pago em aplicativo de banco: cerca de 5 segundos depois, a cobrança vira `paid` sozinha, `paidAt` é preenchido e chega o `charge.paid`. Os eventos de teste chegam com `livemode: false`. **Dica:** no sandbox todo Pix é aprovado. Se a cobrança não virar `paid` em alguns segundos, crie outra. A conta precisa ter Pix habilitado; sem isso, a resposta é `422` com `Fees not configured`.

> [accordion] CHG-06: consulta
>
> Comprova que o seu sistema consegue conferir o estado real de uma cobrança. Isso é necessário porque os webhooks não têm assinatura HMAC: antes de liberar produto ou acesso, a integração confirma o status na API.
>
> **Rota:** `GET /v1/charges/{id}`. **Dica:** o campo `splits` só vem vazio em contas sem regra de split padrão. Se a sua conta tem uma regra padrão para a moeda e o método, `splits` vem preenchido mesmo sem `split` na criação. Para um `id` que não existe, a resposta hoje é `200` com corpo vazio.

> [accordion] CHG-07: estorno total
>
> Comprova que o seu sistema estorna uma cobrança paga e reage ao `charge.refunded`. A API faz só estorno total, e cada cobrança aceita um único estorno.
>
> **Rota:** `POST /v1/refunds` com `chargeId` e `reason` (os dois obrigatórios). **Dica:** antes de repetir um estorno após timeout, consulte a cobrança: se já estiver `refunded`, não envie de novo. Um segundo pedido recebe `422` com `Já existe um reembolso para esta cobrança`, e uma cobrança que não está `paid` recebe `404` com `Cobrança não encontrada`.

> [accordion] CHG-08 e CHG-09: recebimento e simulação de webhook
>
> O CHG-08 comprova que o endpoint aceita POST, responde rápido com status `2xx` e processa o evento depois. O CHG-09 comprova que o endpoint trata eventos de outros status e um evento repetido sem duplicar o efeito.
>
> **Rota da simulação:** `POST /v1/charges/{id}/resend-webhook`, com `status` no corpo (`paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis` ou `authentication_required`); funciona só para cobranças de teste. Ela não reenvia o evento original nem altera a cobrança: gera um evento novo `charge.{status}`, com `id` novo. **Dica:** como o `id` é novo, a proteção contra efeito duplicado vem da checagem do pedido (por exemplo, não liberar duas vezes um pedido já pago).

> [accordion] CHG-10: item físico com endereço
>
> Comprova que o seu fluxo envia `shippingAddress` em toda venda com item `physical`. São obrigatórios `postalCode`, `addressLine1`, `city`, `state` e `country` (3 letras, ex.: `BRA`). `addressLine2` e `neighborhood` são opcionais.
>
> **Rota:** `POST /v1/charges` com itens `physical`. Sem `shippingAddress`, a API responde `400` antes de criar a cobrança, sem gerar `id` nem webhook:
>
> ```json theme={null}
> { "message": "Shipping info must be provided for merchants selling physical items.", "error": "Bad Request", "statusCode": 400 }
> ```
>
> Se o endereço vier incompleto ou inválido, o erro também é `400`, com `message` em lista (ex.: `["shippingAddress.country must be a valid ISO31661 Alpha3 code"]`). **Dica:** a evidência é a requisição sem endereço com o `400` e a mesma requisição com o endereço com `201`.

## B. Cobrança com split

Cenários para quem envia o campo `split` nas cobranças.

Pré-requisito: os recebedores do split (`merchantId`) devem existir e pertencer ao seu grupo Connect. Na criação, o campo é `split` (singular), cada item com `merchantId` e `percentage` (0,01 a 100). Na consulta `GET /v1/charges/{id}`, o campo é `splits` (plural), e cada item traz:

| Campo | O que é |
| - | - |
| `destinyMerchantId` | Conta recebedora (o `merchantId` enviado em `split`) |
| `destinyMerchantName` | Nome fantasia da conta recebedora |
| `splitPercentage` | Percentual, como texto decimal (ex.: `"30.00000000"`). Converta para número antes de comparar |
| `splitAmount` | Valor exibido para o recebedor, número com 2 casas (truncado) |
| `referenceAmount` | Base de cálculo: `net` (valor líquido, o padrão) ou `gross` (valor bruto, quando a conta é configurada assim) |

Se a cobrança não traz `split`, a API aplica a regra de split padrão da conta para aquela moeda e método (em subconta sem regra própria, vale a da conta master). Nesse caso `splits` vem preenchido mesmo sem `split` na criação.

Referências: [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) · [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)

**Em validação (V-64):** split combinado com 3DS gerenciado tem um erro conhecido em correção. Não homologue essa combinação antes da correção.

| Código | Cenário | Resultado esperado | Evidência a enviar |
| - | - | - | - |
| SPL-01 | Cobrança **com split para 1 recebedor** (ex.: 30%), aprovada | Status `paid`; `GET /v1/charges/{id}` retorna `splits` com `destinyMerchantId`, `splitPercentage` e `splitAmount` | Requisição (com `split`) + resposta + GET mostrando `splits` |
| SPL-02 | Cobrança **com split para 2 ou mais recebedores** somando até 100% | Aprovada; `destinyMerchantId`, `splitPercentage` e `splitAmount` de cada recebedor conferem no GET | Requisição + GET com todos os `splits` |
| SPL-03 | Split com **percentual inválido** (0, acima de 100, ou soma inconsistente) | A API **rejeita** com erro de validação | Requisição + resposta de erro (comprovar tratamento) |
| SPL-04 | Split para **`merchantId` inexistente ou fora do grupo** | A API **rejeita** | Requisição + resposta de erro |
| SPL-05 | **Conferência do valor** destinado a cada recebedor | `splitPercentage` igual ao enviado e `splitAmount` coerente com a base (valor líquido × percentual, ou um valor menor enquanto a simulação de antecipação estiver ativa) | `GET /v1/charges/{id}` com os valores de `splits` |
| SPL-06 | Split em **Pix** e em **cartão parcelado** (se ambos forem usados) | Split aplicado corretamente nos dois métodos | Requisição + GET de cada método |

### Por que cada cenário existe e como executar

> [accordion] SPL-01 e SPL-02: um e vários recebedores
>
> Comprovam que a divisão chega à cobrança e pode ser conferida depois. A soma dos percentuais não pode passar de 100%; o que sobra fica com quem originou a venda.
>
> **Rota:** `POST /v1/charges` com `split`, autenticada com a chave de quem origina a venda. **Dica:** para a venda ficar vinculada a uma subconta, autentique com a chave da subconta.

> [accordion] SPL-03 e SPL-04: validações do split
>
> Comprovam que o seu sistema trata a rejeição de um split inválido e interrompe a venda. Teste percentual `0`, percentual acima de `100`, soma acima de 100% e um `merchantId` que não existe ou não pertence ao grupo.
>
> **Rota:** `POST /v1/charges`. **Dica:** valide os percentuais no seu sistema antes de chamar a API, e mostre na evidência que o erro foi tratado.

> [accordion] SPL-05: conferência do valor
>
> Este é o cenário que confirma se a comissão calculada é a que chega. Por padrão, a Finvia aplica o percentual sobre o **valor líquido**, depois da taxa transacional da cobrança.
>
> Enquanto houver parcelas a liquidar e nenhuma antecipação concluída, o `splitAmount` é uma simulação: mostra quanto o recebedor teria se o originador antecipasse, já descontada a taxa de antecipação estimada. Se a cobrança liquidar sem antecipação, o repasse é o percentual sobre o valor líquido, e a consulta passa a mostrar esse valor depois que as parcelas liquidam. Por isso, confira o `splitPercentage` e a coerência do `splitAmount` com a base de cálculo. Se a sua plataforma cobra comissão sobre o bruto, o percentual precisa ser ajustado. Exemplo: em uma venda de R\$ 100,00 no cartão 2x, com 5% de taxa transacional e R\$ 0,40 de taxa fixa, o líquido é R\$ 94,60, e uma comissão de 2% sobre o bruto (R\$ 2,00) exige `percentage` `2.1142`. A taxa de antecipação só entra na conta se o originador antecipar.
>
> **Rota:** `GET /v1/charges/{id}`. **Dica:** compare com o cálculo do seu sistema, usando as taxas de `GET /v1/fast-connect/sub-accounts/{id}/fees-info`.

> [accordion] SPL-06: Pix e cartão parcelado
>
> As taxas de Pix e de cartão parcelado são diferentes, então o percentual calculado também muda. O cenário comprova que o split funciona nos dois métodos que você usa.
>
> **Rota:** `POST /v1/charges` e `GET /v1/charges/{id}` para cada método.

## C. Connect (subcontas)

Cenários para quem usa o Connect para cadastrar e operar subcontas.

Referências: [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md) · [Criar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-subconta.md) · [Enviar documentos](https://docs.fastpaybrasil.com/referencia/fast-connect/enviar-documentos.md) · [Chaves da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/chaves-de-api.md) · [Criar saque](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque.md) · [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md)

| Código | Cenário | Resultado esperado | Evidência a enviar |
| - | - | - | - |
| FC-01 | **Criar subconta** com todos os campos obrigatórios (dados da empresa, representante legal, conta bancária) | Subconta criada; retorna o `id`; status inicial de análise | Requisição + resposta + `id` |
| FC-02 | **Enviar os documentos** da subconta (um por tipo: contrato social, cartão CNPJ, documento do responsável frente e verso, selfie com documento) | Cada envio retorna sucesso; a subconta passa a ter todos os documentos | Evidência de cada upload (tipo enviado + resposta) |
| FC-03 | **Consultar a subconta** até a aprovação | Status evolui até `active`; credenciamento concluído | Resposta da consulta mostrando `active` |
| FC-04 | **Obter as chaves de API** da subconta (quando ativa) | Retorna as chaves da subconta | Resposta (chaves podem vir mascaradas na evidência) |
| FC-05 | **Criar uma cobrança na subconta** usando a chave dela | Cobrança `paid` vinculada à subconta | Requisição + resposta + `id` |
| FC-06 | **Cobrança com split** entre subcontas do grupo | Split aplicado (ver seção B) | Referência ao cenário SPL correspondente |
| FC-07 | **Saque da subconta** (valor em **reais**: `100` = R\$ 100,00) | Conferência de contrato: requisição montada com `amount` em reais e tratamento da resposta `{ "id" }` e dos erros documentados. Não executável com a chave de teste | Requisição montada pelo seu sistema + tratamento dos erros |
| FC-08 | **Recebimento do aviso de status de conta** (mudança de status da subconta) | Aviso recebido e respondido com **`2xx`** | Print/log do aviso |

### Por que cada cenário existe e como executar

> [accordion] FC-01: criar subconta
>
> Comprova que o cadastro envia todos os obrigatórios: `legalName`, `tradeName`, `companyTaxId`, `website`, `averageMonthlyRevenue`, `averageOrderValue`, `productType`, `legalRepresentative`, `contactEmail`, `productDescription`, `address`, `phones`, `bankAccount` e `canAccessDashboard` (com `user` quando `true`).
>
> **Rota:** `POST /v1/submerchants`, com a chave da conta master. **Dica:** guarde também os `id` de `legalRepresentatives` da resposta, usados no envio de documentos de sócios.

> [accordion] FC-02: documentos
>
> Comprova que cada tipo de documento é enviado com o nome de campo certo (`social_contract`, `cnpj_card`, `responsible_document_front`, `responsible_document_back`, `selfie_with_document`), em formato aceito (JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF) e com até 50MB.
>
> **Rota:** `POST /v1/submerchants/{id}/document` em `multipart/form-data`, ou o fluxo com token (`POST /v1/submerchants/{merchantId}/document/upload-token` e `POST /v1/document-uploads`) para sócios adicionais. **Dica:** depois da aprovação, novos envios são bloqueados.

> [accordion] FC-03 e FC-08: acompanhamento do status
>
> O FC-03 comprova que o seu sistema acompanha a subconta até `active`. O FC-08 comprova que o seu servidor recebe o aviso de mudança de status, que chega sem envelope, em camelCase (`merchantId`, `status`, `date` e, em `rejected` e `correcting`, `rejectionReason`).
>
> **Rota:** `GET /v1/submerchants/{id}`. O aviso vai para a `postbackUrl` informada em `POST /v1/submerchants`, que fica salva nas configurações da subconta. Sem ela, a subconta herda a URL de aviso da conta master, se houver. Para trocar a URL depois do cadastro, fale com o suporte. O aviso não vai aos endpoints de webhook do painel nem à `postbackUrl` das cobranças. **Dica:** só `pre_approved`, `correcting`, `active` (aprovação e desbloqueio), `rejected` e `blocked` geram aviso; `pending` e `inactive` não. Só uma resposta `2xx` conta como entregue. Deduplique por `merchantId` + `status` + `date`.

> [accordion] FC-04 e FC-05: chaves e cobrança na subconta
>
> Comprovam que a venda fica vinculada à subconta certa. A cobrança precisa ser autenticada com a chave da própria subconta.
>
> **Rotas:** `GET /v1/submerchants/{id}/api-keys` e `POST /v1/charges`. **Dica:** use as chaves para cobrar só com a subconta `active`. Se a rota de chaves responder `404`, confira o `id` e o status da subconta. Em modo de teste, as chaves têm prefixo `sk_test_` e `pk_test_`.

> [accordion] FC-06: split entre subcontas
>
> Repete os cenários da seção B no contexto do grupo Connect. Indique na evidência qual cenário SPL corresponde.

> [accordion] FC-07: saque da subconta
>
> Comprova que o seu sistema pede o saque em reais e trata as respostas. O saque sai por Pix para a chave CNPJ da subconta, em `BRL`, com mínimo de R\$ 1,00, e sempre passa por aprovação manual.
>
> **Rota:** `POST /v1/submerchants/{merchantId}/payout-requests` com o corpo `{ "amount": 100 }`, autenticada com Basic e a `sk_` da conta master com Connect habilitado. A resposta de sucesso é `{ "id" }`. Com a chave de teste, a API responde `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`: não existe saque no sandbox. Por isso, este cenário é uma **conferência de contrato**: mostre a requisição que o seu sistema monta e como ele trata `422` (ex.: `SubMerchant account is not active`, `Insufficient balance. Required: X, Available: Y`) e o `400` de validação com `message` em lista. Se preferir, combine com o suporte um saque real de valor baixo em produção. **Dica:** a subconta precisa estar ativa, com CNPJ cadastrado como chave Pix e taxa de saque configurada.

## D. Apple Pay

Cenários para quem oferece Apple Pay no checkout.

Pré-requisito: o domínio ou os domínios onde o botão aparece devem estar **registrados e verificados** via API ([registrar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio.md), hospedar o arquivo de verificação, [validar domínio](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-dominio.md)), conforme o [guia de Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md). As rotas de domínio usam a `sk_`; o registro vale para teste e produção ao mesmo tempo. Não é necessária conta Apple Developer nem certificados. A cobrança Apple Pay é enviada como cartão de crédito acompanhada do objeto de carteira (`wallet` com o token do Apple Pay), sempre em `BRL` e com `customer.document` presente.

Referências: [Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) · [Listar domínios](https://docs.fastpaybrasil.com/referencia/apple-pay/listar-dominios.md) · [Validar sessão](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao.md) · [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)

| Código | Cenário | Resultado esperado | Evidência a enviar |
| - | - | - | - |
| AP-01 | **Obter o token de pagamento** no front (Apple Pay JS / PassKit) | Token de pagamento gerado pelo dispositivo | Estrutura do token (pode ser redigida) |
| AP-02 | **Cobrança Apple Pay aprovada** (cartão de crédito + `wallet` com o token) | Status `paid`; a cobrança é processada como cartão | Requisição (com `wallet`) + resposta + `id` |
| AP-03 | **Domínio registrado e verificado** (`GET /v1/apple-pay/domains`) | Domínio com `status: "verified"`; sessão validada pelo `POST /v1/apple-pay/validate-merchant` sem erro | Resposta do GET mostrando `verified` |
| AP-04 | **Tratamento de recusa** | Não aplicável no sandbox com o token da Apple, que sai aprovado. Comprove o tratamento da recusa com o cartão `4444333322221112` em uma cobrança de cartão comum | Requisição + resposta com `refused` (cobrança de cartão comum) |
| AP-05 | **Estorno** de uma cobrança Apple Pay paga | Status `refunded`; webhook `charge.refunded` | Requisição de estorno + resposta + webhook |
| AP-06 | **Recebimento do webhook** `charge.paid` | Evento recebido e respondido com **`2xx`** | Print/log do webhook |

### Por que cada cenário existe e como executar

> [accordion] AP-01 e AP-03: token e domínio
>
> O AP-03 comprova a preparação: domínio registrado, arquivo hospedado em `/.well-known/apple-developer-merchantid-domain-association` (sem extensão, `text/plain`, sem redirecionamento) e domínio `verified`. O AP-01 comprova que o front-end valida a sessão com a chave pública e recebe o token no evento `onpaymentauthorized`.
>
> **Rotas:** `GET /v1/apple-pay/domains` (com a `sk_`) e `POST /v1/apple-pay/validate-merchant` (com a `pk_` ou a `pk_test_`, a partir do navegador). **Dica:** cada hostname é um registro próprio (`www.loja.com.br` e `loja.com.br` são domínios diferentes). Uma chave `pk_test_` valida a sessão no provedor real, mas a cobrança correspondente é simulada.

> [accordion] AP-02 e AP-04: aprovação e recusa
>
> O AP-02 comprova que o backend envia o `payment.token` sem alterações em `paymentMethod.wallet.token`, com `installments` (de `1` a `12`), `currency` `BRL` e `customer.document`. No sandbox, a cobrança Apple Pay não tem um número de cartão controlável e sai aprovada; não há como forçar a recusa com o token da Apple. Por isso, o AP-04 aceita a recusa demonstrada com o cartão `4444333322221112` em uma cobrança de cartão comum, desde que o seu checkout use o mesmo tratamento de recusa para Apple Pay.
>
> **Rota:** `POST /v1/charges`, com a chave secreta. **Dica:** sem `customer.document`, a API responde `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`; com outra moeda, `APPLE_PAY_CURRENCY_NOT_SUPPORTED`.

> [accordion] AP-05 e AP-06: estorno e webhook
>
> Iguais aos cenários CHG-07 e CHG-08, aplicados a uma cobrança Apple Pay.

## E. Saques (payout)

Cenários para quem faz o saque da **própria conta**. O saque de **subconta** (Connect) está no cenário FC-07.

Referências: [Criar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md) · [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) · [Consultar saldo](https://docs.fastpaybrasil.com/referencia/carteiras/listar.md) · [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md)

> [!WARNING]
>
> **Saques não podem ser executados com a chave de teste.** `POST /v1/payout-requests` com `sk_test_` responde `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, e a listagem com a chave de teste só traz registros de teste (na prática, vazia). Por isso, os cenários desta seção são uma **conferência de contrato**: você mostra a requisição que o seu sistema monta e como ele trata cada resposta documentada. A alternativa é combinar com o suporte um saque real de valor baixo em produção.

Como funciona o saque da própria conta, para montar a conferência:

| Item | Regra |
| - | - |
| Rota e autenticação | `POST /v1/payout-requests`, com Basic e a `sk_`. A chave precisa ser de um perfil com permissão de saque: chave de usuário Desenvolvedor recebe `403` com `Acesso negado` |
| Corpo | `merchantId` (id da própria conta), `amount` (em reais, maior que zero, aceita decimais), `currency` `BRL` e `externalAccountDetails` `{ "type": "pix" }` |
| Destino | Pix para a chave CNPJ da própria conta. Cadastre esse CNPJ como chave Pix em uma conta bancária da empresa antes de sacar. Não é possível escolher outra chave |
| Resposta de sucesso | `201` **sem corpo**. Para obter o `id`, use `GET /v1/payout-requests` (do mais recente para o mais antigo) |
| Status | `pending` (criado, valor reservado), `approved` (aprovado e enviado para pagamento) e `rejected` (recusado, valor volta ao saldo disponível) |
| Limites | Valor máximo por saque configurado para a sua conta. Por padrão, um saque `pending` por moeda |
| Taxa | A taxa de saque da conta é descontada: o valor transferido é `netAmount`. Na listagem, `amount` e `payoutFee` chegam como texto decimal (ex.: `"100.00000000"`) |
| Webhook | Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de conta sem Connect não gera webhook: acompanhe pela listagem |

| Código | Cenário | Resultado esperado | Evidência a enviar |
| - | - | - | - |
| PAY-01 | **Consultar o saldo** disponível antes do saque | `GET /v1/wallets` com `merchantId` devolve o saldo por moeda e `isWithdrawalEnabled` | Resposta da consulta de saldo (em produção) ou o trecho do código que a lê |
| PAY-02 | Montar o **saque via Pix** (valor em **reais**) | Corpo com `merchantId`, `amount`, `currency` `BRL` e `externalAccountDetails.type` `pix`; `201` sem corpo tratado, com o `id` buscado na listagem | Requisição montada + tratamento do `201` |
| PAY-03 | **Saldo insuficiente** | `422` com `Insufficient balance. Required: X, Available: Y` tratado | Trecho que trata o erro + mensagem exibida ao usuário |
| PAY-04 | Saque **acima do limite** da conta | `422` com `Maximum withdrawal amount is X` tratado | Trecho que trata o erro |
| PAY-05 | **Segundo saque com um já pendente** na mesma moeda | `422` com `You already have a pending withdrawal request for this currency` tratado | Trecho que trata o erro |
| PAY-06 | **Acompanhar o status** do saque pela listagem | Status lidos de `GET /v1/payout-requests`: `pending`, `approved` ou `rejected` | Trecho que lê a listagem e trata os três status |
| PAY-07 | **Valor em reais** (teste de sanidade) | O fluxo envia o valor em reais; um valor em centavos geraria um saque 100 vezes maior | Requisição mostrando o valor em reais |

### Por que cada cenário existe e como executar

> [accordion] PAY-01: saldo antes do saque
>
> Comprova que o seu sistema consulta o saldo disponível antes de pedir o saque, evitando pedidos sem saldo.
>
> **Rota:** `GET /v1/wallets` com `merchantId` (obrigatório) e, opcionalmente, `currency`, autenticada com Basic e a `sk_`. A resposta é uma lista com `balance.available`, `balance.pending` e `balance.reserved` por moeda, e `isWithdrawalEnabled`. **Dica:** se `isWithdrawalEnabled` vier `false`, não ofereça o saque.

> [accordion] PAY-02: saque por Pix
>
> Comprova que o pedido de saque é montado corretamente e que o `201` sem corpo é tratado. **Dica:** valor em reais, com casas decimais quando necessário (`100.50` = R\$ 100,50). Se a resposta for `422` com `Payout execution failed: ...` (acontece só em contas com aprovação automática), consulte a listagem antes de tentar de novo: o pedido pode ter ficado criado como `pending`.

> [accordion] PAY-03, PAY-04 e PAY-05: regras de negócio
>
> Comprovam que o seu sistema trata as recusas por regra: saldo insuficiente, valor acima do limite máximo por saque configurado para a sua conta e saque pendente na mesma moeda. Todas chegam como `422`, com a mensagem em inglês. **Dica:** decida pelo código HTTP e mostre ao usuário um texto próprio. O PAY-05 não se reproduz em contas com Pix de aprovação automática nem em contas liberadas para mais de um saque pendente.

> [accordion] PAY-06: acompanhamento
>
> Comprova que o seu sistema acompanha o saque pela listagem, já que o saque da própria conta não tem webhook. **Rota:** `GET /v1/payout-requests`, com `merchantId`, `status`, `currency`, `createdAtStart`, `createdAtEnd` (datas `AAAA-MM-DD`), `page` e `size`. Não envie `orderBy`. `approved` significa aprovado e enviado para pagamento: no Pix, a transferência do valor líquido sai no momento da aprovação.

> [accordion] PAY-07: sanidade do valor
>
> Um teste deliberado para confirmar que o fluxo trabalha em reais. Mostre a requisição com o valor em reais e explique, na evidência, como o seu sistema converte o valor digitado pelo usuário.

## F. Cartão salvo e assinaturas

Cenários para quem registra cartões ou cria assinaturas.

> [!WARNING]
>
> **O que é simulado e o que é real neste bloco:**
>
> * O **cadastro do cartão** (`POST /v1/cards`) é real mesmo com a chave de teste: o cartão é guardado no cofre e registrado na adquirente, sem nenhuma cobrança.
> * A **cobrança com cartão salvo** (`POST /v1/charges` com `cardTokenId`) é simulada no Modo Teste.
> * As **assinaturas** cobram de verdade, inclusive a validação de R\$ 1,00 (com estorno) dos planos com trial grátis.
> * O cofre é o mesmo para teste e produção: um `cardTokenId` criado na homologação cobra de verdade se for usado com a chave de produção.
>
> Para homologar assinaturas, use um **cartão real com valor baixo** e **cancele a assinatura no mesmo dia**: o cancelamento em até 7 dias da criação estorna automaticamente todas as cobranças pagas.

Referências: [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) · [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md) · [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md) · [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)

| Código | Cenário | Resultado esperado | Evidência a enviar |
| - | - | - | - |
| SUB-01 | **Registrar cartão** (`POST /v1/cards`, customer com e-mail e CPF/CNPJ) | Cartão criado com `status: "active"` e `pendingActivation: false` | Requisição (sem o PAN na evidência) + resposta + `id` |
| SUB-02 | **Cobrança one-click com cartão salvo** (`POST /v1/charges` com `cardTokenId` + `cvv`) | Status `paid` (simulado no Modo Teste); comprovar que o CVV do comprador é coletado a cada cobrança | Requisição + resposta + `id` |
| SUB-03 | **Criar plano** (`POST /v1/subscription-plans`, moeda `BRL`) | Retorna `{ "id": ... }` | Requisição + resposta |
| SUB-04 | **Criar assinatura** (`POST /v1/subscriptions` com `cardTokenId` ou cartão inline) | Status `active`; primeira cobrança processada | Requisição + resposta + `id` |
| SUB-05 | **Receber `subscription.created` e `subscription.activated`** | Eventos recebidos e respondidos com **`2xx`** | Print/log dos webhooks |
| SUB-06 | **Cancelar dentro de 7 dias** (`POST /v1/subscriptions/{id}/cancel`) | `cancellationType: "regret"`, `refunded: true`; estorno das cobranças pagas conferido | Requisição + resposta + webhook `subscription.cancelled` |

### Por que cada cenário existe e como executar

> [accordion] SUB-01 e SUB-02: cartão salvo
>
> O SUB-01 comprova que o cliente tem e-mail e CPF ou CNPJ (outros documentos são recusados) e que o cartão nasce `active`, sem etapa de ativação. Sem e-mail ou documento, a resposta é `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`. O SUB-02 comprova que a recompra pede o CVV a cada cobrança: sem ele, a resposta é `400` com `CVV is required when using cardTokenId`.
>
> **Rotas:** `POST /v1/customers`, `POST /v1/cards` e `POST /v1/charges` com `cardTokenId`, `cvv` e `installments`. **Dica:** no Modo Teste, a cobrança do SUB-02 é simulada e segue as regras dos cartões de teste aplicadas ao número guardado. Como o cartão salvo costuma ser real, ela sai aprovada.

> [accordion] SUB-03 e SUB-04: plano e assinatura
>
> Comprovam a criação do plano em `BRL` e da assinatura com primeira cobrança aprovada. Para homologar com custo mínimo, crie um plano de valor baixo e sem trial.
>
> **Rotas:** `POST /v1/subscription-plans` e `POST /v1/subscriptions`. **Dica:** se o plano tiver trial grátis, a Finvia cobra R\$ 1,00 para validar o cartão e estorna em seguida; essa validação não gera webhook.

> [accordion] SUB-05: webhooks de assinatura
>
> Comprova que o endpoint recebe os eventos de assinatura, no envelope padrão com campos em snake\_case.

> [accordion] SUB-06: cancelamento por arrependimento
>
> Comprova o cancelamento dentro de 7 dias, com estorno automático das cobranças pagas, e encerra o custo do teste.
>
> **Rota:** `POST /v1/subscriptions/{id}/cancel`, com `reason` opcional (até 500 caracteres). **Dica:** cancele no mesmo dia da criação. Anexe a resposta e o webhook `subscription.cancelled` com `cancellation_type` `regret`.

## Envio das evidências

Não existe formulário de homologação. Ao final, fale com o suporte da Finvia para agendar a homologação e enviar as evidências, organizadas com **uma linha por cenário** deste roteiro (código, resultado e anexos). A equipe Finvia confere as evidências com você.

> [!TIP]
>
> **Como saber que terminou:** todos os cenários das funcionalidades que você integrou têm evidência anexada e resultado igual ao esperado. Se a equipe Finvia apontar um cenário com problema, corrija a integração e envie a nova evidência antes da virada.

## Resumo por funcionalidade

| Se você integrou | Execute |
| - | - |
| Cobrança Pix e cartão | CHG-01 a CHG-10 |
| Split | SPL-01 a SPL-06 |
| Subcontas Connect | FC-01 a FC-08 |
| Apple Pay | AP-01 a AP-06 |
| Saque da própria conta | PAY-01 a PAY-07 |
| Cartão salvo e assinaturas | SUB-01 a SUB-06 |

## Veja também

> [card] [Checklist de go-live](https://docs.fastpaybrasil.com/homologacao/checklist-go-live.md)
>
> O que conferir na virada para produção.

> [card] [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)
>
> Chave de teste, chave de produção e permissões.

> [card] [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Canais, envelopes, entrega e idempotência.

> [card] [Casos de uso](https://docs.fastpaybrasil.com/casos-de-uso/visao-geral.md)
>
> Quais cenários cada modelo de negócio precisa.


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