Como ler a coluna de autenticação
A chave age com as permissões do usuário que a gerou. Uma chave de perfil sem permissão recebe
403 com Acesso negado (veja Permissões da chave). Como montar o Basic: Credenciais e ambientes.
O desenho abaixo mostra de onde parte cada chamada e qual credencial ela usa.
Visão geral por grupo
O desenho abaixo organiza os grupos na ordem em que costumam aparecer em uma integração, da preparação da conta ao saque.
A ordem é uma sugestão. Os grupos que você vai usar dependem do seu modelo de negócio, como mostram os casos de uso.
Cobranças
Apple Pay
Rotas para preparar o Apple Pay na sua própria integração. Registrar o primeiro domínio ativa na conta o modelo em que a sessão é validada porvalidate-merchant. A cobrança em si usa a rota padrão POST /v1/charges.
As rotas de domínio exigem que o usuário dono da chave tenha permissão de domínios Apple Pay (perfis Owner, Manager e Desenvolvedor). Em
validate-merchant, a pk_test_ também valida a sessão no provedor real, porque a janela de pagamento do Safari só abre com sessão real.Saldos e meios de pagamento
Saques
Clientes
Cartões
O cartão já nasce
active no cadastro, sem etapa de ativação.
3D Secure
Planos de assinatura
Assinaturas
Para o negócio: as chaves geradas por usuários Desenvolvedor ou Financeiro recebem
403 em todas as rotas de planos e assinaturas, e a chave de Desenvolvedor também ao criar cobrança. O perfil Visualizador só acessa as consultas. Use uma chave de usuário Owner ou Manager.Connect
Rotas do módulo de marketplace. Exigem o Connect habilitado pela Finvia na conta master.
Os saques das subcontas são acompanhados pela listagem
GET /v1/payout-requests, que, para a conta master, traz também os saques das subcontas. Filtre por merchantId para ver uma conta só.
Endpoints de webhook
Rotas para cadastrar pela API os endereços que recebem os webhooks, inclusive os de uma subconta. O corpo usa snake_case, e omerchantId da conta vai na query.
O endpoint cadastrado pelo painel (Configurações > Webhooks) recebe todos os eventos. O filtro por evento (
enabled_events) só existe pela API; lista vazia significa todos.Veja também
Introdução à referência
Convenções da referência da API.
Conceitos essenciais
O que é cada objeto que aparece nas rotas.
Paginação, ordenação e idempotência
Como funcionam as rotas de listagem.
Catálogo de códigos de erro
As mensagens de erro de cada rota.

