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):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 parchave: é convertido para Base64.
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 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. orderByemGET /v1/submerchantsusa os nomes das colunas em snake_case (legal_name,-created_at).- Nas respostas de
GETde cobrança, as chaves demetadatavoltam em camelCase. Envie-as nesse formato para lê-las iguais em todos os canais (veja Metadata). - Valores de saque (
amount,payoutFee,netAmount) e osplitPercentagedo 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, comopsp_ref_idepaid_at; os objetos aninhados da cobrança ficam em camelCase. O postbackcharge.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 em1) esize(itens por página, padrão10).limite outros parâmetros desconhecidos são ignorados sem erro. Algumas listagens devolvem um array simples, sem paginação, comoGET /v1/wallets. - A maior parte das listagens tem ordem fixa, da mais recente para a mais antiga.
orderBysó funciona emGET /v1/submerchants, com nomes em snake_case. - O cabeçalho
Idempotency-Keynão existe hoje: depois de um timeout, siga o procedimento descrito em 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.
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.
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.

