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.Gere a chave de teste
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.Escolha as seções que se aplicam
Guarde as evidências de cada cenário
Envie as evidências ao suporte
Convenções de evidência
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.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çaPor que cada cenário existe e como executar
CHG-01 e CHG-02: aprovação à vista e parcelada
CHG-01 e CHG-02: aprovação à vista e parcelada
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.CHG-03: recusa
CHG-03: recusa
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.CHG-04 e CHG-05: Pix gerado e pago
CHG-04 e CHG-05: Pix gerado e pago
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.CHG-06: consulta
CHG-06: consulta
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.CHG-07: estorno total
CHG-07: estorno total
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.CHG-08 e CHG-09: recebimento e simulação de webhook
CHG-08 e CHG-09: recebimento e simulação de webhook
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).CHG-10: item físico com endereço
CHG-10: item físico com endereço
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: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 camposplit 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:
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
Por que cada cenário existe e como executar
SPL-01 e SPL-02: um e vários recebedores
SPL-01 e SPL-02: um e vários recebedores
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.SPL-03 e SPL-04: validações do split
SPL-03 e SPL-04: validações do split
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.SPL-05: conferência do valor
SPL-05: conferência do valor
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.SPL-06: Pix e cartão parcelado
SPL-06: Pix e cartão parcelado
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 contaPor que cada cenário existe e como executar
FC-01: criar subconta
FC-01: criar subconta
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.FC-02: documentos
FC-02: documentos
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.FC-03 e FC-08: acompanhamento do status
FC-03 e FC-08: acompanhamento do status
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.FC-04 e FC-05: chaves e cobrança na subconta
FC-04 e FC-05: chaves e cobrança na subconta
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_.FC-06: split entre subcontas
FC-06: split entre subcontas
FC-07: saque da subconta
FC-07: saque da subconta
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 ask_; 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
AP-01 e AP-03: token e domínio
AP-01 e AP-03: token e domínio
/.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.AP-02 e AP-04: aprovação e recusa
AP-02 e AP-04: aprovação e recusa
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.AP-05 e AP-06: estorno e webhook
AP-05 e AP-06: estorno e webhook
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 Como funciona o saque da própria conta, para montar a conferência:Por que cada cenário existe e como executar
PAY-01: saldo antes do saque
PAY-01: saldo antes do saque
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.PAY-02: saque por Pix
PAY-02: saque por Pix
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.PAY-03, PAY-04 e PAY-05: regras de negócio
PAY-03, PAY-04 e PAY-05: regras de negócio
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.PAY-06: acompanhamento
PAY-06: acompanhamento
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.PAY-07: sanidade do valor
PAY-07: sanidade do valor
F. Cartão salvo e assinaturas
Cenários para quem registra cartões ou cria assinaturas. Referências: Assinaturas · Registrar cartão · Criar assinatura · Webhooks de assinaturaPor que cada cenário existe e como executar
SUB-01 e SUB-02: cartão salvo
SUB-01 e SUB-02: cartão salvo
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.SUB-03 e SUB-04: plano e assinatura
SUB-03 e SUB-04: plano e assinatura
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.SUB-05: webhooks de assinatura
SUB-05: webhooks de assinatura
SUB-06: cancelamento por arrependimento
SUB-06: cancelamento por arrependimento
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.
