A a C
| Termo | Definição | Na API da Finvia |
|---|---|---|
| 3D Secure (3DS) | Protocolo das bandeiras de cartão que autentica o comprador junto ao banco emissor antes da compra online, por exemplo com uma confirmação no app do banco. | Três formatos: gerenciado (threeDSMode igual a managed), pelo SDK de segurança ou pelas rotas /v1/three-ds/*. Veja 3D Secure. |
| ACS | Access Control Server: o sistema do banco emissor que conduz a autenticação 3DS e apresenta o desafio ao comprador. | Aparece no campo acsTransactionId do resultado 3DS. |
| Adquirente | Empresa que processa as transações de cartão do lojista junto às bandeiras e liquida os valores. Também chamada de credenciadora. | |
| Antecipação | Recebimento antes do prazo original de valores de vendas no cartão, mediante uma taxa. | As taxas de antecipação da subconta aparecem com feeType anticipation em GET /v1/fast-connect/sub-accounts/{id}/fees-info. O webhook de cobrança traz anticipation_fee_estimated. |
| API key | Ver Chave secreta e Chave pública. | |
| Assinatura | Vínculo de um cliente a um plano, com cobrança automática a cada ciclo. | Rotas em /v1/subscriptions. Status: pending_activation, active, cancelled, expired. As cobranças de assinatura são reais mesmo com a chave de teste. |
| Bandeira | Rede do cartão, como Visa, Mastercard e Elo. Define regras de aceitação, contestação e autenticação. | O campo brand do cartão salvo traz a bandeira (ex.: visa). |
| Base64 | Forma de representar bytes como texto usando 64 caracteres. Usada para transportar dados binários ou credenciais em cabeçalhos HTTP. | O cabeçalho de autenticação é o Base64 de sua_chave:. Para conferir, decodifique e veja se termina em :. O QR Code do Pix vem como imagem em Base64 em qrCodeBase64. |
| Basic Auth | Esquema de autenticação HTTP em que usuário e senha vão no cabeçalho Authorization, codificados em Base64. | A chave secreta vai como usuário e a senha fica vazia: Authorization: Basic base64(sk_...:). |
| BIN / first six | Os primeiros dígitos do cartão, que identificam o emissor e o produto. | A API devolve os seis primeiros em firstSix, na resposta da cobrança e no payment_method de cartão do webhook. |
| Bloqueio cautelar | Ferramenta do Pix em que a instituição de quem recebeu retém o valor de forma preventiva e curta quando suspeita de fraude. É diferente do MED. | Na API, aparece como bloqueio da cobrança (isBlocked: true), do mesmo jeito que o MED. Veja Bloqueio, chargeback e MED. |
| BR Code | Padrão do código do Pix, no formato EMV. | É o conteúdo do campo copyPaste. |
| CAVV | Cardholder Authentication Verification Value: o criptograma que comprova a autenticação 3DS. | Campo cryptogram do objeto threeDS, em Base64. Obrigatório para autenticação bem-sucedida. |
| Challenge (desafio) | Etapa do 3DS em que o comprador precisa agir para se autenticar, por exemplo digitando um código ou confirmando no app do banco. | Status requires_challenge e URL em challengeUrl nas rotas de 3DS. |
| Chargeback | Contestação de uma compra com cartão, aberta pelo banco emissor por meio da bandeira. Chega à Finvia pela adquirente. Se prevalece, o valor é devolvido ao portador. | Status chargeback (formalizado), avisado na postbackUrl por charge.updated e, quando o valor é revertido do saldo, também por charge.refunded. O alerta chega por e-mail à conta (no Connect, à conta master) e a defesa é enviada em resposta a esse e-mail, dentro do prazo indicado nele. Não há envio de defesa pela API. Veja Bloqueio, chargeback e MED. |
| Chave pública | Credencial que pode ficar no navegador ou no app, usada só nas rotas que pedem por ela. | Prefixo pk_ (pk_test_ em teste). Usada no 3D Secure, na validação de sessão do Apple Pay e na inicialização do SDK. Obtida no painel, em Configurações > Chave de API. |
| Chave secreta | Credencial que identifica a sua empresa nas chamadas à API. Deve ficar só no servidor. | Prefixo sk_ em produção e sk_test_ no sandbox. Age com as permissões do usuário que a gerou. |
| Cliente (customer) | Quem paga a cobrança. | Objeto customer. Cadastro em POST /v1/customers, com name, email, documentId e documentType obrigatórios. |
| Cobrança (charge) | Pedido de pagamento com valor, cliente, itens e forma de pagamento. | Criada em POST /v1/charges. O valor vai em reais (10 = R$ 10,00), com mínimo 1. |
| Cofre de cartões | Armazenamento seguro de cartões para uso futuro, sem que o lojista guarde o número. | POST /v1/cards devolve o id do cartão salvo. O cofre é o mesmo para teste e produção. Veja Cofre de cartões. |
| Connect | Módulo da Finvia para marketplaces: conta master, subcontas, split e saques. | Habilitado pela Finvia na conta. Veja Connect. |
| Conta master | No Connect, a conta da plataforma que cria e gerencia subcontas. Também chamada de MerchantMaster. | |
| CVV | Código de segurança impresso no cartão. | Obrigatório em toda cobrança avulsa com cartão, inclusive com cartão salvo (cardTokenId). Mínimo de 3 caracteres. |
D a M
| Termo | Definição | Na API da Finvia |
|---|---|---|
| Data URI | Forma de embutir um arquivo dentro de um texto, começando com data: e o tipo do arquivo. | qrCodeBase64 vem como data:image/png;base64,... e pode ir direto no src de uma imagem. |
| Directory Server (DS) | Servidor da bandeira que conecta o lojista ao banco emissor no fluxo 3DS. | Campo directoryServerTransactionId. |
| ECI | Electronic Commerce Indicator: código que indica o resultado da autenticação de uma transação online. | Campo eci. Valores comuns: 05 (autenticado), 06 (tentativa), 07 (não autenticado). |
| End-to-end ID | Identificador único de uma transação Pix, gerado pelo arranjo Pix e usado para rastreio entre bancos. | Campo endToEndId em paymentDetails. |
| Estorno | Devolução ao cliente do valor de uma cobrança paga. | Sempre total, em POST /v1/refunds. Só para cobranças paid e um por cobrança. Veja Estorno. |
| Grupo Connect | Conjunto formado por uma conta master e as subcontas vinculadas a ela. | O split só funciona entre contas do mesmo grupo. A documentação técnica também chama o grupo de “Connect”. |
| Fingerprinting | Coleta de dados do navegador e do dispositivo usada pelo emissor para avaliar o risco no 3DS. | URL em fingerprintingUrl, renderizada em iframe oculto. O resultado vai em fingerprintingResult. |
| Frictionless | Autenticação 3DS concluída sem pedir ação ao comprador, com base nos dados coletados. | No 3DS gerenciado, a cobrança segue direto e a resposta já traz o status final, sem authentication_required. |
| Idempotência | Propriedade de uma operação que, repetida, produz o mesmo efeito que uma única execução. Evita cobranças duplicadas em retentativas. | O cabeçalho Idempotency-Key não existe hoje na API. Veja Idempotência. |
| Item | Cada produto ou serviço incluído na cobrança. | Campos obrigatórios: title, type (physical ou digital), description, unit_price e quantity. Item physical exige shippingAddress na cobrança. |
| JSON | Formato de texto para troca de dados estruturados, com pares de nome e valor. | Corpo de todas as requisições e respostas, exceto uploads de arquivo (multipart/form-data). |
| JWT | JSON Web Token: token assinado que carrega informações de identidade e validade. | O token de upload de documentos é um JWT, enviado como Authorization: Bearer. As demais rotas usam Basic com a chave. |
| KYC / KYB | Know Your Customer / Know Your Business: verificação de identidade de pessoas e empresas antes de operar. | Análise cadastral das subcontas do Connect, com envio de documentos. Veja Subcontas e KYC. |
| Liquidação | Etapa em que o valor de uma venda é acertado e passa a ser repassado a quem tem direito a ele. | No cartão, cada parcela é liquidada 30 dias corridos depois da criação da cobrança (D+30, D+60 e assim por diante). No Pix, no mesmo dia, logo após a confirmação do pagamento. No split, a parte de cada participante é repassada parcela a parcela, nesse mesmo momento, do saldo disponível do originador para o do recebedor. |
| Livemode | Indicador de que um evento veio de produção. | Campo livemode no envelope do webhook: false em cobranças de teste. |
| MED | Mecanismo Especial de Devoluçã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 instituição de quem recebeu analisa o pedido. Durante a análise, o valor fica bloqueado; se a contestação for aceita, ele é devolvido ao pagador. Não confundir com o bloqueio cautelar. | Não há status nem evento chamado MED. A cobrança continua paid, com isBlocked: true, e o evento charge.blocked é enviado aos endpoints e à postbackUrl. O alerta chega por e-mail à conta (no Connect, à conta master) e a defesa é enviada em resposta a esse e-mail, dentro do prazo indicado nele. Não há envio de defesa pela API. |
| Merchant | Empresa cliente da Finvia que vende e recebe. Também chamada de lojista. | Campo merchantId nas respostas. |
| Metadata | Informações livres do lojista guardadas junto a um objeto, como o número do pedido. | Campo metadata na cobrança e na assinatura. Não é filtro de busca em GET /v1/charges. |
| Modo Teste | Ambiente de testes da Finvia, usado com a chave de teste. | A chave sk_test_ é gerada no painel, em Configurações > Chave de API, aba Teste. As cobranças são simuladas; o cadastro de cartão e as assinaturas não. Os endpoints de webhook são os mesmos da produção: os eventos de teste trazem livemode: false. Veja Credenciais e ambientes. |
O a S
| Termo | Definição | Na API da Finvia |
|---|---|---|
| Originador | No split, a conta que cria a cobrança. | É a conta cuja chave secreta foi usada em POST /v1/charges. Fica com o que sobra do líquido depois das partes do split. |
| Paginação | Divisão de uma listagem em páginas para não devolver todos os registros de uma vez. | Parâmetros page (começa em 1) e size (padrão 10) em todas as listagens paginadas. limit é ignorado. GET /v1/cards e GET /v1/wallets devolvem lista sem paginação. |
| Parcelamento | Divisão do valor de uma compra no cartão em parcelas mensais na fatura do comprador. | Campo installments, de 1 a 12 parcelas. |
| Payload | O conteúdo transportado em uma requisição ou notificação, normalmente o corpo JSON. | |
| Payout | Ver Saque. | |
| Pix | Sistema brasileiro de pagamentos instantâneos. | paymentMethod.type igual a pix, com validade mínima de 900 segundos. Veja Pix. |
| Pix copia e cola | Código de texto que representa uma cobrança Pix. O pagador cola esse código no app do banco quando não pode ler o QR Code. | Campo copyPaste em paymentDetails. |
| Plano | Modelo de cobrança recorrente com preço, moeda e periodicidade. | Rotas em /v1/subscription-plans. Periodicidade: weekly, biweekly, monthly ou custom. |
| Portador | Titular do cartão usado na compra. | |
| Postback | Notificação enviada à URL informada em uma cobrança específica. | Campo postbackUrl. Recebe os mesmos eventos de cobrança dos endpoints, só daquela cobrança, e também o charge.updated legado, que não vai aos endpoints. |
| Pré-chargeback | Alerta de contestação recebido antes de o chargeback ser formalizado, por programas das bandeiras. | Status pre_chargeback, avisado pelo evento charge.pre_chargeback. chargebackAlertRefunded (no webhook, chargeback_alert_refunded) diz se o valor já foi devolvido. |
| PSP | Payment Service Provider: provedor que processa pagamentos em nome de lojistas. | Os campos pspRefId e pspRefundRefId trazem a referência da operação no provedor. |
| QR Code | Código gráfico que o celular lê com a câmera. No Pix, carrega o BR Code da cobrança. | Imagem PNG de 256x256 em qrCodeBase64. Pode vir null: nesse caso, gere a imagem a partir do copyPaste. |
| Sandbox | Ambiente de testes em que nenhuma transação é real. | Mesma URL da produção, com a chave sk_test_. Toda cobrança via POST /v1/charges é simulada, inclusive com cartão salvo. O cadastro de cartão e as assinaturas não têm sandbox, e não existe saque no sandbox (detalhes). |
| Saque | Transferência do saldo da conta para fora da Finvia. | Sempre por Pix, para a chave CNPJ da conta que saca, em BRL. Da própria conta em POST /v1/payout-requests; da subconta em POST /v1/submerchants/{merchantId}/payout-requests (mínimo R$ 1,00). Status: pending, approved (aprovado e enviado para pagamento) e rejected. |
| Soft descriptor | Nome curto que aparece na fatura do cartão do comprador. | Campo softDescriptor da subconta, com até 40 caracteres. |
| Split | Divisão automática do valor de uma cobrança entre contas. | Campo split da cobrança, com merchantId e percentage (0,01 a 100). Aplicado por padrão sobre o valor líquido. Só entre contas do mesmo grupo Connect. Na consulta da cobrança, aparece em splits. Não vale para as cobranças recorrentes de assinatura. |
| Spread | Spread aplicado à cobrança. | Campo spread da cobrança e dos webhooks. O campo net traz o valor líquido depois de aplicado o spread. |
| Status | Situação atual de um objeto, como cobrança, assinatura ou saque. | Veja Status de cobrança. |
| Subadquirente / subcredenciadora | Empresa que processa pagamentos para lojistas usando a estrutura de um adquirente, concentrando o credenciamento de vários lojistas. | |
| Subconta | No Connect, a conta de cada vendedor vinculada à conta master. Também chamada de SubMerchant. | Rotas em /v1/submerchants. Só opera com status active. Na criação, recebe uma cópia das taxas da conta master; depois disso, as taxas são independentes. |
T a Z
| Termo | Definição | Na API da Finvia |
|---|---|---|
| Taxa de saque | Valor cobrado por solicitação de saque. | Parte fixa mais percentual, configurada por conta. O valor transferido é netAmount. Valores de saque chegam como texto decimal (ex.: "1.00000000"). |
| Timeout | Tempo esgotado sem resposta em uma requisição. O resultado da operação fica incerto. | Antes de repetir uma criação, confirme o estado. Veja Paginação, ordenação e idempotência. |
| Token de cartão | Identificador que substitui o número do cartão guardado no cofre. | O id devolvido por POST /v1/cards, usado como cardTokenId. |
| Token de upload | Credencial temporária para enviar documentos sem expor a chave secreta. | Emitido por POST /v1/submerchants/{merchantId}/document/upload-token, expira em 300 segundos. |
| Trial | Período de teste de um plano de assinatura, grátis ou pago. | Objeto trial do plano, com durationDays de 1 a 365 e isFree. |
| Valor bruto | Valor total da venda, pago pelo cliente. | É o amount da cobrança. |
| Valor líquido | O que sobra da venda depois das taxas da Finvia. | No split, o percentual de cada recebedor incide sobre o valor líquido. A cobrança traz o campo net, que o contrato descreve como o valor líquido depois de aplicado o spread. Veja Cálculo de split. |
| Wallet (carteira) | Saldo da conta por moeda. Também é o nome do objeto do Apple Pay na cobrança. | GET /v1/wallets traz available, pending e reserved. Na cobrança, paymentMethod.wallet carrega o token do Apple Pay. |
| Webhook | Notificação HTTP POST que a Finvia envia ao seu servidor quando algo acontece. | Quatro famílias: cobrança, assinatura, saque e conta. Os endpoints são cadastrados no painel (Configurações > Webhooks) ou em POST /v1/webhook-endpoints e recebem cobrança, assinatura e saque (os de saque, só de subcontas). O aviso de status de subconta vai para a postbackUrl informada na criação da subconta. Veja o Catálogo de eventos. |
Veja também
Conceitos essenciais
Os objetos da API explicados com mais contexto.
Mapa da API
Todas as rotas em uma página.
Status de cobrança
Cada status e o que fazer.
Catálogo de eventos
Todos os eventos de webhook.

