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

# Checklist de go-live

> O que conferir na virada para produção: chave de produção, domínios, webhooks, tratamento de status, valores, segurança, monitoramento e um checklist por funcionalidade.

Com a homologação concluída, a virada para produção é uma troca de chave. Antes dela, confira o que só aparece com dinheiro real: permissões, segredos, endpoints públicos, monitoramento e o plano para disputas. Use esta página como lista de verificação, item por item, antes de liberar o primeiro cliente real.

> [!NOTE]
>
> **Para o negócio:** a API não tem trava técnica de homologação: a chave de produção existe assim que a conta é aprovada. Por isso, a decisão de virar é sua, e o roteiro de homologação, acompanhado pela equipe Finvia, é a etapa recomendada antes dela. Este checklist ajuda a não esquecer o que fica fora dos cenários: quem gerou a chave, onde ela está guardada, quem acompanha disputas e o que fazer se algo sair do ar.

O desenho abaixo resume a virada para produção: o que conferir antes, a troca de chave e o que fazer depois.

```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
    H(["Homologação concluída<br/>evidências enviadas"]):::ok
    subgraph ANTES["Antes da virada"]
        K["Chave de produção<br/>de Owner ou Manager"]:::lojista
        W["Webhooks de produção<br/>em HTTPS, eventos de<br/>teste descartados"]:::lojista
        U["URLs e domínios<br/>acessíveis"]:::lojista
    end
    T["Troque sk_test_ por sk_<br/>e pk_test_ por pk_<br/>a URL continua a mesma"]:::finvia
    subgraph DEPOIS["Depois da virada"]
        R["Transação real de valor<br/>baixo em cada método"]:::lojista
        M["Acompanhe as<br/>primeiras horas"]:::lojista
        D["Desligue o que era<br/>só de teste"]:::lojista
    end
    OK(["Virada concluída<br/>com rastreio pelo id"]):::ok
    H --> K
    H --> W
    H --> U
    K --> T
    W --> T
    U --> T
    T --> R --> M --> D --> OK
    style ANTES fill:#F7F9FC,stroke:#D5DCE6
    style DEPOIS fill:#F7F9FC,stroke:#D5DCE6
    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
```

## Antes da virada

**1. Evidências da homologação conferidas**

Os cenários das funcionalidades que você integrou têm evidência e resultado igual ao esperado, e as evidências foram enviadas ao suporte da Finvia. Veja o [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

**2. Chave de produção do usuário certo**

No painel, em **Configurações > Chave de API**, aba **Produção**, clique em **Revelar chave** e informe o código enviado ao seu e-mail. O par `sk_`/`pk_` de produção é criado automaticamente no cadastro ou na aprovação da conta e pertence ao proprietário, com acesso a todas as rotas. Se usar uma chave gerada por outro usuário, ela age com as permissões dele: use um usuário **Owner** ou **Manager** (veja [Permissões da chave](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#permissões-da-chave)).

Guarde a chave direto no cofre de segredos ou na variável de ambiente do servidor de produção.

**3. Troca de sk\_test\_ para sk\_**

A URL é a mesma para sandbox e produção. O ambiente é definido só pela chave: troque a chave de teste (`sk_test_`) pela de produção (`sk_`), e a pública de teste (`pk_test_`) pela de produção (`pk_`), onde ela for usada. Se você usa subcontas do Connect, busque as chaves de produção de cada subconta com `GET /v1/submerchants/{id}/api-keys`.

**4. URL da API e domínios**

Confirme que a sua configuração usa estes endereços e que eles estão acessíveis a partir dos seus servidores e do navegador dos seus clientes:

| Para quê | Endereço |
| - | - |
| API | `https://api-global.fastpaybrasil.com` |
| Painel | `https://app.finvia.com.br` |
| Documentação | `https://docs.fastpaybrasil.com` |
| SDK de 3D Secure via CDN | `https://js.fastpaybrasil.com/security-sdk.min.js` |

No 3DS gerenciado, leve o comprador ao endereço recebido em `authenticationUrl`, sem montar nem alterar a URL. As URLs de documentos de sócios são assinadas, expiram em 1 hora e têm o domínio do provedor de armazenamento: não fixe esse domínio nem guarde a URL.

**5. Webhooks de produção**

Os endpoints de webhook não têm modo: a sua conta tem uma única lista, que recebe eventos de teste e de produção, e o painel não tem uma lista separada para o Modo Teste. O endpoint usado na homologação continua recebendo eventos de teste depois da virada. Por isso:

* descarte ou separe os eventos de teste: `livemode: false` e `data.is_test: true` no envelope padrão de cobrança, `data.isTest` no `charge.updated`;
* se quiser URLs diferentes por ambiente, use a `postbackUrl`, que é definida em cada cobrança;
* confira se a `postbackUrl` enviada nas cobranças de produção aponta para o endereço de produção, sempre em **HTTPS**;
* retire túneis de desenvolvimento (como ngrok) da configuração.

**6. Simulação de webhook só no sandbox**

`POST /v1/charges/{id}/resend-webhook` é um simulador, disponível só para cobranças de teste. Ele gera um evento novo, com `id` novo, a cada chamada. Rotinas que dependiam dele não funcionam em produção.

## Checklist geral

### Credenciais e segurança

* [ ] Chave de produção (`sk_`) do proprietário ou gerada por Owner ou Manager
* [ ] Chave secreta só no servidor, em variável de ambiente ou cofre de segredos; nunca no código, no repositório, no navegador ou no aplicativo
* [ ] Chave pública (`pk_`) usada só nas rotas que pedem por ela (Apple Pay `validate-merchant`, rotas de 3D Secure e SDK)
* [ ] Chaves de teste e de produção separadas por ambiente; a chave de produção nunca é usada em testes
* [ ] Chaves das subcontas guardadas em cofre, associadas a cada subconta
* [ ] Processo de **troca de chave** definido: quem pede a troca ao suporte, onde atualiza a `sk_` no servidor e a `pk_` no front-end (as duas mudam juntas), e troca imediata em caso de suspeita de vazamento
* [ ] Acesso aos logs restrito ao time responsável

### Webhooks

* [ ] Endpoints em HTTPS, acessíveis pela internet, sem autenticação que bloqueie a Finvia
* [ ] Endpoint responde com status **`2xx`** em até 10 segundos, antes de processar a lógica pesada. Qualquer outra resposta, inclusive redirecionamento, conta como falha de entrega (veja a política de entrega em [Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md))
* [ ] **Idempotência persistente**: os `id` de evento já processados ficam em banco de dados ou cache persistente
* [ ] **Validação via API**: antes de liberar produto, acesso ou dinheiro, o sistema confirma o estado com `GET /v1/charges/{id}`, porque os webhooks não têm assinatura HMAC
* [ ] Tratamento do `charge.updated` (só no `postbackUrl`, sem `id` e `livemode`, campos em camelCase), deduplicado pela combinação `event` + `data.id` + `data.status` + `data.isBlocked` + `data.chargebackAlertRefunded` + `data.updatedAt`, como na [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos)
* [ ] Tratamento dos formatos de campos: snake\_case no primeiro nível de `data` no envelope padrão (objetos aninhados em camelCase, `metadata` como enviada), camelCase na API, no `charge.updated`, nos avisos de conta e nos eventos de saque
* [ ] Eventos de teste (`livemode: false`) descartados ou separados no ambiente de produção
* [ ] Rate limiting no endpoint, para proteção contra abuso
* [ ] Rotina de conferência pela API para eventos que não chegaram, em especial saques (pela listagem)

### Tratamento de status

* [ ] Cobrança: `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`, `pre_chargeback` e `chargeback`; bloqueio por `isBlocked`
* [ ] `authentication_required` tratado já na resposta da criação, com o comprador levado à `authenticationUrl`
* [ ] Recusa no cartão tratada pela resposta da criação, com o motivo de `reason`; `charge.refused` e `charge.failed` tratados como complemento
* [ ] Estorno: a resposta hoje traz `refunded`; um status diferente cai no caso padrão
* [ ] Assinatura: `active`, `pending_activation`, `cancelled` e `expired`
* [ ] Subconta: `pending`, `pre_approved`, `correcting`, `active`, `rejected`, `blocked` e `inactive`
* [ ] Saque: `pending`, `approved` (aprovado e enviado para pagamento) e `rejected`
* [ ] Um caso padrão (`default`) que registra status ou eventos desconhecidos sem quebrar o processamento

### Valores e dados

* [ ] Todos os valores em **reais**: `amount`, `unit_price`, `price` do plano e `amount` do saque (`10` = R\$ 10,00)
* [ ] `shippingAddress` em toda venda com item `physical`, com `postalCode`, `addressLine1`, `city`, `state` e `country` em 3 letras (`BRA`)
* [ ] Valores de saque (`amount`, `payoutFee`, `netAmount`) e `splitPercentage` convertidos de texto decimal para número antes de calcular
* [ ] Percentuais de split calculados sobre o valor líquido, com taxas consultadas na API

### Logs e privacidade

* [ ] Logs **sem dados de cartão**: número completo, CVV e validade nunca são gravados
* [ ] Logs sem a chave secreta e sem o cabeçalho `Authorization`
* [ ] Logs com o `id` de cada cobrança, assinatura, subconta e saque, para rastrear casos com o suporte
* [ ] URLs assinadas de documentos de sócios não são guardadas (expiram em 1 hora)

### Duplicidade e falhas de rede

* [ ] A API não tem `Idempotency-Key`: depois de um timeout na criação, o sistema segue o [procedimento de timeout](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#procedimento-depois-de-um-timeout-ao-criar-cobrança) (identificador do pedido em `metadata`, webhook `charge.created` e busca por `createdAtStart`, `createdAtEnd` e `searchFor`) antes de criar de novo
* [ ] O `id` de cada cobrança é salvo no seu sistema no momento da criação, porque a listagem não busca por `metadata`
* [ ] Timeout de cliente generoso na criação de cobrança (por exemplo, 60 segundos)
* [ ] `GET /v1/charges/{id}` com corpo vazio tratado como "não encontrada"
* [ ] Antes de reenviar um estorno, o sistema consulta a cobrança; se ela já estiver `refunded`, não envia de novo

### Monitoramento

* [ ] Alerta para aumento de respostas `401`, `403`, `422` e `500` da API
* [ ] Alerta para endpoint de webhook fora do ar ou respondendo com status fora de `2xx`
* [ ] Painel interno com cobranças `pending` antigas, assinaturas com `payment_failed` e saques pendentes
* [ ] Fechamento diário comparando cobranças pagas na Finvia com pedidos pagos no seu sistema

### Plano para chargeback e MED

O MED (Mecanismo Especial de Devolução) é o mecanismo do Pix que permite à instituição de quem pagou pedir a devolução em caso de fundada suspeita de fraude ou falha operacional. O chargeback é a contestação de uma compra no cartão.

* [ ] Tratamento de `charge.blocked` (cobrança continua `paid`, com `isBlocked: true`): marcar como em disputa. O evento vai aos endpoints e à `postbackUrl`
* [ ] Rotina que consulta as cobranças bloqueadas (`GET /v1/charges?status=blocked`), porque a liberação do bloqueio não gera webhook; use `isBlocked` para saber se continua bloqueada
* [ ] Tratamento de `charge.pre_chargeback` e de `charge.refunded` com `chargeback_alert_refunded: true` (alerta com estorno)
* [ ] `postbackUrl` enviada nas cobranças de cartão, porque o chargeback formalizado chega nela como `charge.updated` com `status: "chargeback"`; quando o valor é revertido do saldo, chega também `charge.refunded`. Confirme com `GET /v1/charges/{id}`
* [ ] Responsável definido para reunir as evidências da venda (comprovante de entrega, registro de acesso, comunicação com o cliente) e enviá-las em resposta ao e-mail de alerta de chargeback ou MED, dentro do prazo indicado nele. O alerta vai para o e-mail da conta (no Connect, da conta master): garanta que ele chega a esse responsável. Não existe envio de defesa pela API
* [ ] Política interna de reembolso alinhada com o atendimento

Detalhes em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

## Checklist por funcionalidade

> [tab] Pix
>
> * [ ] Validade definida com `expirationInDays` (mínimo `1`) ou `expirationInSeconds` (mínimo `900`)
> * [ ] QR Code exibido a partir de `qrCodeBase64`, com `copyPaste` quando a imagem vier `null`
> * [ ] Pedido marcado como pago só com `charge.paid` e status confirmado na API
> * [ ] Rotina para Pix não pago ao fim da validade, com consulta antes de cancelar o pedido (a expiração não gera evento nos endpoints; ela chega à `postbackUrl` como `charge.updated`)
> * [ ] Cenários CHG-04 a CHG-09 concluídos

> [tab] Cartão
>
> * [ ] `number` só com dígitos, `expirationYear` com 4 dígitos, `cvv` com pelo menos 3
> * [ ] `installments` de `1` a `12`
> * [ ] Recusa tratada na resposta, com outra forma de pagamento oferecida
> * [ ] Dados do cartão trafegam só entre o navegador, o seu servidor e a Finvia, em HTTPS, sem gravação
> * [ ] Se usar 3DS gerenciado: `browser` com `userAgent` e `ipAddress`, e tratamento de `authentication_required`
> * [ ] Cenários CHG-01, CHG-02, CHG-03, CHG-06 a CHG-08 e CHG-10 concluídos

> [tab] Cartão salvo
>
> * [ ] Cliente com e-mail e CPF ou CNPJ antes de registrar o cartão
> * [ ] Cartão com `status` `active`
> * [ ] CVV coletado do comprador a cada cobrança
> * [ ] Cartão usado só pela conta que o registrou
> * [ ] Cartões salvos durante a homologação revisados: o cofre é o mesmo para teste e produção, e um `cardTokenId` de teste cobra de verdade com a chave de produção
> * [ ] Cenários SUB-01 e SUB-02 concluídos

> [tab] Apple Pay
>
> * [ ] Todos os hostnames de produção registrados e com `status` `verified`
> * [ ] Arquivo de verificação servido sem extensão, em `text/plain`, sem redirecionamento
> * [ ] Validação de sessão com a chave pública de produção
> * [ ] `customer.document` coletado antes de abrir a folha de pagamento; moeda `BRL`
> * [ ] `supportedNetworks` com `visa` e `masterCard`
> * [ ] Cenários AP-01 a AP-06 concluídos

> [tab] Assinaturas
>
> * [ ] Planos de produção criados em `BRL`, com a chave de produção
> * [ ] Aviso ao comprador sobre a validação de R\$ 1,00 em planos com trial grátis
> * [ ] Tratamento de `pending_activation`, `firstCharge.pending` e `CARD_VALIDATION_FAILED`
> * [ ] Acesso controlado por `subscription.activated`, `renewed`, `payment_failed`, `cancelled` e `expired`
> * [ ] Acesso mantido até o fim do período pago no cancelamento regular
> * [ ] Assinatura de homologação cancelada (cenário SUB-06)
> * [ ] Cenários SUB-01 a SUB-06 concluídos

> [tab] Connect e split
>
> * [ ] Connect habilitado na conta de produção
> * [ ] Subcontas de produção criadas com a chave de produção e com KYC aprovado
> * [ ] Chaves de produção de cada subconta obtidas e guardadas
> * [ ] Cobranças criadas com a chave da subconta que origina a venda
> * [ ] Percentual de split calculado com `fees-info` de produção e soma até 100%
> * [ ] Tratamento dos avisos de status das subcontas
> * [ ] Cenários FC-01 a FC-08 e SPL-01 a SPL-06 concluídos

> [tab] Saques
>
> * [ ] Autenticação Basic com a `sk_` de um perfil com permissão de saque (chave de Desenvolvedor recebe `403`)
> * [ ] Saque da própria conta em `POST /v1/payout-requests` com `externalAccountDetails` `{ "type": "pix" }`; `201` sem corpo tratado, com o `id` buscado na listagem
> * [ ] CNPJ da conta (e de cada subconta) cadastrado como chave Pix em uma conta bancária da empresa
> * [ ] Valor em reais; na subconta, mínimo de R\$ 1,00
> * [ ] Subconta ativa, com CNPJ e taxa de saque configurados
> * [ ] Eventos `payout.approved` e `payout.rejected` recebidos nos endpoints da subconta ou nos da master com a opção de incluir subcontas (saques da própria conta não geram webhook)
> * [ ] Acompanhamento pela listagem `GET /v1/payout-requests` (`pending`, `approved`, `rejected`)
> * [ ] Cenários FC-07 e, se aplicável, PAY-01 a PAY-07 conferidos

## Depois da virada

**1. Faça uma transação real de valor baixo**

Crie uma cobrança real de valor baixo em cada método integrado, confira o webhook, a baixa no seu sistema e o estorno.

**2. Acompanhe as primeiras horas**

Observe os alertas de erro da API e de entrega de webhooks. Confira no painel se os eventos estão sendo entregues com sucesso.

**3. Desligue o que era só de teste**

Remova endpoints de túnel, chaves de teste esquecidas em configuração de produção e rotinas que simulavam eventos com o reenvio de webhook do sandbox.

> [!TIP]
>
> A virada está concluída quando a primeira transação real de cada método foi criada, notificada por webhook, conciliada no seu sistema e, no teste de estorno, devolvida, com todos os registros rastreáveis pelo `id`.

## Veja também

> [card] [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Cenários e evidências.

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

> [card] [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md)
>
> Códigos HTTP e respostas de erro.

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


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