Quem participa
Merchant (lojista)
O merchant é a empresa cliente da Finvia que vende e recebe. É a sua empresa. Toda cobrança, cliente, cartão salvo e plano pertence a um merchant, e o merchant é identificado pela chave usada na requisição. Em respostas da API, o campomerchantId indica a qual conta um objeto pertence.
Conta master e subconta (Connect)
O Connect é o módulo da Finvia para marketplaces e plataformas que atendem vários vendedores. Ele é habilitado pela Finvia na sua conta e cria uma hierarquia de duas camadas:
Na criação, a subconta recebe uma cópia das taxas e configurações vigentes da conta master. Depois disso, as taxas da subconta são independentes: alterar as taxas da master não muda as das subcontas já criadas. Antes de vender, ela passa por análise cadastral (KYC, a verificação de identidade da empresa e dos sócios) e só opera depois de aprovada, com status
active.
Para o negócio: com o Connect, cada venda fica registrada na conta do vendedor que vendeu, e a comissão da plataforma é separada automaticamente pelo split. Isso dá rastreabilidade por vendedor e evita repasses manuais.
Cliente (customer)
O cliente é quem paga: a pessoa ou empresa que compra do merchant. Na API, é o objetocustomer. Há duas formas de informar o cliente em uma cobrança:
- Cadastro prévio: você cria o cliente com
POST /v1/customers(name,email,documentIdedocumentTypeobrigatórios) e depois envia só ocustomer.idna cobrança. - Cadastro junto com a cobrança: você envia
nameeemail(ouphone) dentro da cobrança, e a API cria ou localiza o cliente.
PUT /v1/customers/{id} aceita só name, email e phoneNumber.
O que é cobrado
Cobrança (charge)
A cobrança (charge) é o pedido de pagamento: quanto cobrar, de quem, pelo quê e por qual meio. É o objeto central da API, criado emPOST /v1/charges. Ela nasce com um id único, que é a chave para consultar, estornar e conciliar a cobrança com os webhooks.
Campos obrigatórios na criação: amount, currency, customer, paymentMethod e items.
O valor vai em reais: "amount": 10 significa R$ 10,00 e "amount": 99.9 significa R$ 99,90. O mínimo é 1.
Item
Cada cobrança traz a listaitems, com o que está sendo vendido. Todos os campos do item são obrigatórios: title, type, description, unit_price e quantity.
O type do item é physical (produto físico) ou digital (produto digital ou serviço). Se algum item da cobrança for physical, o endereço de entrega (shippingAddress) é obrigatório, com postalCode, addressLine1, city, state e country (addressLine2 e neighborhood são opcionais). Sem ele, a API responde 400 e não cria a cobrança.
Forma de pagamento
A Finvia aceita dois meios de pagamento: cartão de crédito (digitado, salvo no cofre ou via Apple Pay) e Pix. A forma de pagamento vai no objetopaymentMethod da cobrança e é identificada pelo campo type:
A rota
GET /v1/payment-methods lista os meios de pagamento habilitados para a sua conta.
Status
O status diz em que ponto da vida a cobrança está. Ele muda ao longo do tempo, e o seu sistema acompanha essas mudanças pelos webhooks ou consultando a cobrança.
A tabela completa, com o que fazer em cada status, está em Status de cobrança. O bloqueio de uma cobrança em disputa não é um status: a cobrança continua
paid e passa a ter isBlocked: true (veja Bloqueio).
Para o negócio: a regra mais segura para liberar um pedido, enviar um produto ou dar acesso a um curso é esperar o status
paid. pending e in_analysis ainda não significam dinheiro recebido.Ciclo de vida de uma cobrança
Cobrança Pix
1
Seu sistema cria a cobrança
Você chama
POST /v1/charges com paymentMethod.type igual a pix e a validade do QR Code (expirationInDays ou expirationInSeconds, mínimo de 900 segundos, ou seja, 15 minutos).2
A API devolve o QR Code
A resposta
201 traz status pending e, em paymentDetails, o código copia e cola (copyPaste) e a imagem do QR Code (qrCodeBase64). Seu checkout mostra essas informações ao cliente.3
A Finvia avisa que a cobrança foi criada
Os webhooks
charge.created e charge.pending chegam aos endpoints cadastrados no painel e à postbackUrl da cobrança, se informada.4
O cliente paga no app do banco
O pagamento é feito fora do seu sistema, no aplicativo bancário do cliente.
5
A Finvia confirma o pagamento
O webhook
charge.paid chega com status paid e a data em paid_at. A partir daí, você pode liberar o pedido. No sandbox, o Pix de teste vira paid sozinho, cerca de 5 segundos depois da criação.Cobrança com cartão de crédito
1
Seu sistema cria a cobrança
Você chama
POST /v1/charges com paymentMethod.type igual a credit_card, os dados do cartão (ou o cardTokenId de um cartão salvo, ou o wallet do Apple Pay) e o número de parcelas (installments, até 12).2
Autenticação 3D Secure, quando aplicável
Com o 3D Secure gerenciado (
threeDSMode igual a managed), quando a política 3DS da conta dispara e o banco emissor pede verificação ou desafio, a cobrança nasce com authentication_required e traz a authenticationUrl, para onde o comprador é levado. A própria página dessa URL conduz a autenticação e retoma a cobrança, que só é processada depois disso. Na autenticação sem atrito, a resposta já traz o status final.3
A resposta traz o resultado
Na resposta
201, o status já indica aprovação (paid), recusa (refused) ou falha (failed). Em recusas, o campo reason explica o motivo, e o checkout pode oferecer outra forma de pagamento em seguida.4
A Finvia notifica o resultado
O webhook
charge.paid (aprovação), charge.refused (recusa) ou charge.failed (falha) chega aos endpoints cadastrados e à postbackUrl. A resposta síncrona continua sendo a fonte principal; o webhook é complementar.5
Pós-venda, se houver
Estorno total (
refunded), alerta de contestação (pre_chargeback) ou chargeback (chargeback), cada um com sua notificação.Como o seu sistema fica sabendo
Webhook e postback
Um webhook é uma notificação que a Finvia envia ao seu servidor, por uma requisição HTTP POST com corpo em JSON, quando algo acontece. Assim você não precisa consultar a API o tempo todo para saber se uma cobrança foi paga. Existem dois canais para eventos de cobrança, e eles se complementam:
O webhook de cobrança tem um envelope com
id (identificador do evento), event (nome do evento), livemode (false em cobranças de teste) e data (a cobrança). Os mesmos endpoints recebem eventos de teste e de produção: separe-os por livemode. O charge.updated tem formato próprio, sem id e sem livemode. Detalhes em Webhooks e no Catálogo de eventos.
Depois da venda
Estorno
O estorno devolve ao cliente o valor de uma cobrança paga. Na API ele é sempre total: estorno parcial não é suportado. Só cobranças comstatus paid podem ser estornadas (as demais recebem 404), e cada cobrança aceita um único estorno (um segundo pedido recebe 422). A rota é POST /v1/refunds, com chargeId e reason. Funciona para Pix e cartão de crédito.
Chargeback, pré-chargeback e MED
- Chargeback é a contestação de uma compra com cartão, aberta pelo banco emissor do cartão por meio da bandeira. A disputa chega à Finvia pela adquirente, e a decisão final é do emissor ou da bandeira. Se a contestação prevalece, o valor volta ao portador e a cobrança fica
chargeback. - Pré-chargeback é um alerta recebido antes de o chargeback ser formalizado. A cobrança vai para
pre_chargebacke o eventocharge.pre_chargebacké enviado. O campochargebackAlertRefunded(no webhook,chargeback_alert_refunded) diz se o valor já foi devolvido ao portador (true) ou se a disputa segue aberta sem estorno (false). - MED (Mecanismo Especial de Devolução) é o mecanismo do Pix, definido pelo Banco Central, que permite à instituição de quem pagou pedir a devolução de um Pix quando há fundada suspeita de fraude ou falha operacional. A contestação é analisada pela instituição de quem recebeu. Durante a análise, o valor fica bloqueado; se a contestação for aceita, ele é devolvido ao pagador. O MED existe só no Pix.
Bloqueio
Quando há um MED, um chargeback em análise ou outra suspeita, a equipe Finvia pode bloquear uma cobrançapaid. O bloqueio não chega automaticamente do banco: é aplicado pela Finvia. Na API, não existe status nem evento chamado MED. O que você vê é:
- a cobrança continua com
statuspaide passa a terisBlocked: true,blockedAteblockedReason(texto livre, que pode vir vazio); - o evento
charge.blockedvai aos endpoints e àpostbackUrlda cobrança, e apostbackUrlrecebe também ocharge.updatedlegado; - o valor já liquidado da venda sai do saldo disponível e vai para o saldo bloqueado;
GET /v1/charges?status=blockedlista as cobranças bloqueadas.
Detalhes em Bloqueio, chargeback e MED.
Cartões e recorrência
Cartão salvo (cofre e token)
O cofre de cartões guarda o cartão do cliente de forma segura na Finvia. Ao registrar um cartão comPOST /v1/cards, você recebe um id (o token do cartão) e passa a usar esse identificador no lugar do número. O cartão pertence ao merchant da chave que o registrou e não pode ser usado por outro merchant ou subconta.
Regras que mudam o desenho do produto:
- Para registrar, o cliente precisa ter e-mail e CPF ou CNPJ. Outros documentos, como passaporte, são recusados.
- Com o processador atual, o cartão já nasce
active. Não há transação de teste nem etapa de ativação. - Em uma cobrança avulsa com cartão salvo (
cardTokenId), o CVV do comprador é obrigatório toda vez. Para cobrar sem o comprador presente, use assinaturas. - O cofre é o mesmo para teste e produção: um
cardTokenIdcriado com a chave de teste cobra de verdade se for usado com a chave de produção.
Plano e assinatura
A periodicidade do plano (
recurrenceType) pode ser weekly, biweekly, monthly ou custom. Editar um plano não altera assinaturas existentes: preço, moeda e periodicidade ficam congelados no momento da contratação. Uma assinatura aceita só alteração de metadata. Para trocar cartão ou plano, cancele e crie outra. Detalhes em Assinaturas.
Para o negócio: cancelamentos em até 7 dias da criação da assinatura são tratados como arrependimento e estornam automaticamente todas as cobranças pagas. Depois disso, o cancelamento é regular: as cobranças param imediatamente, sem estorno, e a sua plataforma controla o acesso até o fim do período pago.
Dinheiro em movimento
O desenho abaixo mostra o caminho do dinheiro, da cobrança paga até o saque na conta bancária. O split só acontece entre contas do mesmo grupo Connect. As regras de cada etapa estão nas seções abaixo.Split (divisão de valores)
O split divide o valor de uma cobrança entre contas do mesmo grupo Connect (a conta master e as subcontas dela). Você informa no camposplit da cobrança quais contas recebem e qual percentual de cada uma. Sem split, vale a regra de split padrão da conta para aquela moeda e método, se houver (em subconta sem regra própria, vale a da master).
- A soma dos percentuais não pode passar de 100%. O que sobra fica com o originador, a conta que criou a cobrança.
- Todas as contas precisam pertencer ao mesmo grupo Connect.
- Por padrão, o percentual é aplicado sobre o valor líquido, depois da taxa transacional. O uso do valor bruto é configurado pela Finvia, sob consulta.
- O valor de cada participante é calculado na criação da cobrança e repassado a cada parcela, quando o recebível do originador é liquidado: no cartão, cada parcela em D+30, D+60 e assim por diante; no Pix, no mesmo dia, logo após a confirmação do pagamento. O repasse sai do saldo disponível do originador e entra no saldo disponível do recebedor.
- As cobranças recorrentes de assinatura não recebem split.
Para o negócio: se a sua plataforma cobra uma comissão de 10% sobre o valor bruto da venda, o percentual de split precisa ser maior que 10% para entregar o mesmo valor, porque a base é o líquido. O cálculo está em Cálculo de split.
Saldo e carteira (wallet)
A carteira (wallet) mostra o saldo da conta por moeda, em três partes:available (disponível), pending (a liberar) e reserved (reservado). O campo isWithdrawalEnabled diz se saques estão habilitados naquela moeda. A rota é GET /v1/wallets.
Saque (payout)
O saque (payout) transfere saldo para fora da Finvia, sempre por Pix para a chave CNPJ da conta que saca (o mesmo CNPJ do cadastro). Antes de sacar, cadastre esse CNPJ como chave Pix em uma conta bancária da empresa. As rotas de saque usam Basic com a chave secreta, e não existe saque no Modo Teste: com a chave de teste, a criação responde403.
A taxa de saque é descontada do valor (
netAmount é o líquido). Os status são:
O acompanhamento é pela listagem
GET /v1/payout-requests.
Ambientes e chaves
A Finvia usa o mesmo endereço para testes e produção:https://api-global.fastpaybrasil.com. O ambiente é definido pela chave.
A chave age com as permissões do usuário que a gerou. No Modo Teste, toda cobrança via
POST /v1/charges é simulada, inclusive com cartão salvo. O cadastro de cartão registra o cartão de verdade (sem cobrar) e as assinaturas cobram de verdade mesmo com a chave de teste. Como gerar e usar as chaves: Credenciais e ambientes.
Veja também
Glossário
Definições curtas de termos de pagamentos e da API.
Mapa da API
Todas as rotas em uma página.
Sua primeira cobrança
Coloque os conceitos em prática no sandbox.
Status de cobrança
Cada status, quando acontece e o que fazer.

