Skip to main content
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.
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. 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.
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, no fim desta página.

Convenções de evidência

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. 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 · Consultar cobrança · Estornar cobrança · Webhooks de cobrança
Autenticação obrigatória em todos os cenários. O 3D Secure, quando aplicável à sua conta, é coberto pelos guias de 3D Secure.

Por que cada cenário existe e como executar

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.
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.
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.
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.
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.
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).
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:
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: 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 · Criar cobrança
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.

Por que cada cenário existe e como executar

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.
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.
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.
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 · Criar subconta · Enviar documentos · Chaves da subconta · Criar saque · Webhooks de conta

Por que cada cenário existe e como executar

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.
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.
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.
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_.
Repete os cenários da seção B no contexto do grupo Connect. Indique na evidência qual cenário SPL corresponde.
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, hospedar o arquivo de verificação, validar domínio), conforme o guia de Apple Pay. 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 · Listar domínios · Validar sessão · Criar cobrança

Por que cada cenário existe e como executar

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.
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.
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 · Listar saques · Consultar saldo · Saldos e meios de pagamento
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:

Por que cada cenário existe e como executar

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.
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.
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.
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.
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.
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 · Registrar cartão · Criar assinatura · Webhooks de assinatura

Por que cada cenário existe e como executar

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.
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.
Comprova que o endpoint recebe os eventos de assinatura, no envelope padrão com campos em snake_case.
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ê.
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

Veja também

Checklist de go-live

O que conferir na virada para produção.

Credenciais e ambientes

Chave de teste, chave de produção e permissões.

Webhooks

Canais, envelopes, entrega e idempotência.

Casos de uso

Quais cenários cada modelo de negócio precisa.