> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossário

> Termos de pagamentos e da API da Finvia em ordem alfabética, com definições curtas e as regras que a API aplica a cada um.

Definições curtas para consulta rápida. Quando um termo tem uma regra específica na API da Finvia, ela aparece na coluna "Na API da Finvia". Para uma explicação mais longa dos principais objetos, veja [Conceitos essenciais](https://docs.fastpaybrasil.com/conceitos.md).

## 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](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md). |
| **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](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md). |
| **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](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md). |
| **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](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md). |
| **Connect** | Módulo da Finvia para marketplaces: conta master, subcontas, split e saques. | Habilitado pela Finvia na conta. Veja [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md). |
| **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](https://docs.fastpaybrasil.com/guias/estorno.md). |
| **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](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#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](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md). |
| **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](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md). |

## 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](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md). |
| **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](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#o-que-é-simulado-no-modo-teste)). |
| **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](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md). |
| **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](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md). |
| **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](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md). |
| **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](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md). |

## Veja também

> [card] [Conceitos essenciais](https://docs.fastpaybrasil.com/conceitos.md)
>
> Os objetos da API explicados com mais contexto.

> [card] [Mapa da API](https://docs.fastpaybrasil.com/mapa-da-api.md)
>
> Todas as rotas em uma página.

> [card] [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md)
>
> Cada status e o que fazer.

> [card] [Catálogo de eventos](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md)
>
> Todos os eventos de webhook.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.