Skip to main content
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.
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.

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: 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)
  • 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
  • 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 (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.

Checklist por funcionalidade

  • 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

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.