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.
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.
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).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:
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: falseedata.is_test: trueno envelope padrão de cobrança,data.isTestnocharge.updated; - se quiser URLs diferentes por ambiente, use a
postbackUrl, que é definida em cada cobrança; - confira se a
postbackUrlenviada 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 Payvalidate-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 apk_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
2xxem 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) - Idempotência persistente: os
idde 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ó nopostbackUrl, semidelivemode, campos em camelCase), deduplicado pela combinaçãoevent+data.id+data.status+data.isBlocked+data.chargebackAlertRefunded+data.updatedAt, como na receita de deduplicação - Tratamento dos formatos de campos: snake_case no primeiro nível de
datano envelope padrão (objetos aninhados em camelCase,metadatacomo enviada), camelCase na API, nocharge.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_chargebackechargeback; bloqueio porisBlocked -
authentication_requiredtratado 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.refusedecharge.failedtratados como complemento - Estorno: a resposta hoje traz
refunded; um status diferente cai no caso padrão - Assinatura:
active,pending_activation,cancelledeexpired - Subconta:
pending,pre_approved,correcting,active,rejected,blockedeinactive - Saque:
pending,approved(aprovado e enviado para pagamento) erejected - 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,pricedo plano eamountdo saque (10= R$ 10,00) -
shippingAddressem toda venda com itemphysical, compostalCode,addressLine1,city,stateecountryem 3 letras (BRA) - Valores de saque (
amount,payoutFee,netAmount) esplitPercentageconvertidos 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
idde 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 (identificador do pedido emmetadata, webhookcharge.createde busca porcreatedAtStart,createdAtEndesearchFor) antes de criar de novo - O
idde cada cobrança é salvo no seu sistema no momento da criação, porque a listagem não busca pormetadata - 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,422e500da API - Alerta para endpoint de webhook fora do ar ou respondendo com status fora de
2xx - Painel interno com cobranças
pendingantigas, assinaturas compayment_failede 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 continuapaid, comisBlocked: 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; useisBlockedpara saber se continua bloqueada - Tratamento de
charge.pre_chargebacke decharge.refundedcomchargeback_alert_refunded: true(alerta com estorno) -
postbackUrlenviada nas cobranças de cartão, porque o chargeback formalizado chega nela comocharge.updatedcomstatus: "chargeback"; quando o valor é revertido do saldo, chega tambémcharge.refunded. Confirme comGET /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
Checklist por funcionalidade
- Pix
- Cartão
- Cartão salvo
- Apple Pay
- Assinaturas
- Connect e split
- Saques
- Validade definida com
expirationInDays(mínimo1) ouexpirationInSeconds(mínimo900) - QR Code exibido a partir de
qrCodeBase64, comcopyPastequando a imagem viernull - Pedido marcado como pago só com
charge.paide 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 à
postbackUrlcomocharge.updated) - Cenários CHG-04 a CHG-09 concluídos
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.
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
Roteiro de homologação
Cenários e evidências.
Credenciais e ambientes
Geração de chaves e permissões.
Erros e como tratar
Códigos HTTP e respostas de erro.
Webhooks
Canais, idempotência e política de entrega.

