Skip to main content
Esta seção descreve cada rota da API da Finvia com todos os parâmetros, todos os campos de resposta e todos os códigos HTTP do contrato. Use os guias para entender o fluxo de um recurso (Pix, 3D Secure, estorno) e use a Referência para conferir o detalhe de uma chamada: nome exato do campo, tipo, se é obrigatório e o que volta.
Para o negócio: cada página de endpoint começa com um parágrafo sobre para que a rota serve e uma tabela “Quando usar”. Esses trechos ajudam a decidir o que pedir ao time técnico sem precisar ler os parâmetros. Os detalhes técnicos vêm logo depois.

URL base

Todas as rotas usam o mesmo endereço, em produção e no sandbox (ambiente de testes):
O ambiente é definido pela chave enviada. Com uma chave de teste (sk_test_, pk_test_), toda cobrança em POST /v1/charges é simulada, inclusive com cartão salvo. Com uma chave de produção (sk_, pk_), as transações são reais. O cadastro de cartão e as assinaturas não têm sandbox, e não existe saque no sandbox (veja o aviso em Testar no playground). As rotas começam com /v1, por exemplo GET /v1/charges. Outros endereços: o painel fica em https://app.finvia.com.br, e o SDK de 3D Secure via CDN em https://js.fastpaybrasil.com/security-sdk.min.js. No 3DS gerenciado, use o endereço recebido em authenticationUrl, sem montar a URL. As URLs de documentos são assinadas e têm o domínio do provedor de armazenamento (nos exemplos, https://<armazenamento>/documents/...): não fixe esse domínio.

Autenticação

A maior parte da API usa HTTP Basic Auth com a chave secreta: a chave vai no lugar do usuário, a senha fica vazia e o par chave: é convertido para Base64.
O valor acima é o Base64 de sk_abc123:. Para conferir se o seu valor está certo, decodifique o Base64 e veja se ele termina com :. O passo a passo completo, com exemplos em várias linguagens, está em Credenciais e ambientes. Nem todas as rotas usam a mesma credencial: Fora o envio de documentos com token, toda chamada de integração usa uma das chaves da tabela.
A chave secreta (sk_) nunca pode aparecer em código que roda no navegador ou no aplicativo do cliente. A chave pública (pk_) foi feita para o front-end e é a que você usa nas rotas de 3D Secure e na validação de sessão do Apple Pay. A conta precisa estar ativa para a pk_ funcionar.
A chave age com as permissões do usuário que a gerou. A chave de produção criada automaticamente pertence ao proprietário da conta e funciona em todas as rotas. Se for usar uma chave gerada por outro usuário, gere com um perfil Owner ou Manager: chaves de Desenvolvedor recebem 403 com Acesso negado ao criar cobranças, em saldo e em saques, e as de Desenvolvedor e Financeiro também nas rotas de planos e assinaturas (veja Permissões da chave).

Formato dos dados

Exceções que você vai encontrar:
  • Os itens da cobrança usam unit_price (com sublinhado), como está no contrato.
  • Os endpoints de webhook (/v1/webhook-endpoints) recebem o corpo em snake_case (enabled_events, include_submerchants) e respondem em camelCase.
  • orderBy em GET /v1/submerchants usa os nomes das colunas em snake_case (legal_name,-created_at).
  • Nas respostas de GET de cobrança, as chaves de metadata voltam em camelCase. Envie-as nesse formato para lê-las iguais em todos os canais (veja Metadata).
  • Valores de saque (amount, payoutFee, netAmount) e o splitPercentage do split chegam como texto decimal com 8 casas (ex.: "100.00000000"). Converta para número antes de calcular.
  • Os webhooks de cobrança e de assinatura usam snake_case no primeiro nível de data, como psp_ref_id e paid_at; os objetos aninhados da cobrança ficam em camelCase. O postback charge.updated, os avisos de conta e os eventos de saque usam camelCase. Detalhes em Webhooks de cobrança.

Paginação, ordenação e idempotência

  • Todas as listagens paginadas recebem page (começa em 1) e size (itens por página, padrão 10). limit e outros parâmetros desconhecidos são ignorados sem erro. Algumas listagens devolvem um array simples, sem paginação, como GET /v1/wallets.
  • A maior parte das listagens tem ordem fixa, da mais recente para a mais antiga. orderBy só funciona em GET /v1/submerchants, com nomes em snake_case.
  • O cabeçalho Idempotency-Key não existe hoje: depois de um timeout, siga o procedimento descrito em Idempotência.
Regras completas e exemplos em Paginação, ordenação e idempotência.

Erros

Os erros voltam com o código HTTP e um corpo JSON. Há três formatos:
Trate o erro pelo código HTTP e, quando existir, pelo campo code ou error dos dois últimos formatos. As mensagens misturam português e inglês e não devem ser comparadas como texto. Cada página de endpoint lista os códigos da rota. O tratamento recomendado está em Erros e como tratar e as mensagens de cada rota em Códigos de erro.

Como ler uma página de endpoint

Toda página de endpoint segue a mesma ordem:
1

Cabeçalho

Método e rota (ex.: POST /v1/refunds) e o tipo de autenticação.
2

Para que serve, quando usar e antes de chamar

Contexto de negócio, situações de uso e pré-requisitos.
3

Parâmetros

Cada parâmetro aparece com o nome, onde ele vai (path, query ou body), o tipo e o selo required quando é obrigatório. Valores padrão aparecem como default. Limites (mínimo, máximo, tamanho) e valores aceitos (enums) ficam na descrição.
4

Respostas

Todos os campos da resposta de sucesso, seguidos de uma tabela com os códigos HTTP documentados.
5

Exemplos

Exemplo de requisição em cURL e Node.js e exemplos de resposta de sucesso e de erro, no painel lateral.
Objetos aninhados ficam recolhidos. Clique em propriedades (ou no nome da variante, quando o campo pode ter formatos diferentes) para ver os campos internos. Quando um campo recebe um formato diferente por forma de pagamento, cada formato aparece em um bloco separado.
Para o desenvolvedor: um campo sem o selo required pode ser omitido na requisição. Na resposta, um tipo como string | null significa que o campo pode vir null. Escreva o seu código para tolerar campos ausentes e nulos sempre que o tipo indicar isso.

Testar no playground

As páginas de endpoint têm um botão para enviar a requisição direto do navegador. Use sempre uma chave de teste nesse recurso:
  • Em rotas com chave secreta, informe a chave sk_test_ como usuário e deixe a senha vazia.
  • Nas rotas de 3D Secure, informe a chave pública de teste (pk_test_).
  • Em POST /v1/document-uploads, informe o token de upload.
Não use a chave de produção no playground. Mesmo com a chave de teste, o cadastro de cartão (POST /v1/cards) registra o cartão de verdade (sem cobrar) e as assinaturas cobram de verdade. O cofre de cartões é o mesmo para teste e produção.

Veja também

Credenciais e ambientes

Como gerar as chaves e montar o cabeçalho.

Criar uma cobrança

A rota central da API.

Mapa da API

Todas as rotas agrupadas por recurso.

Roteiro de homologação

O que testar antes de ir para produção.