Skip to main content
Use esta página como índice. Cada tabela reúne as rotas de um assunto, explica em linguagem de negócio o que cada uma faz e mostra a autenticação usada. O link da última coluna leva à página de referência, com todos os campos, respostas e exemplos. Todas as rotas usam a mesma URL base, para sandbox e produção:

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

Para o desenvolvedor: GET /v1/charges não busca por metadata nem por identificador do seu pedido, e ignora orderBy. Guarde o id devolvido na criação junto com o seu pedido. Depois de um timeout, siga o procedimento de timeout.

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 por validate-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

Para o desenvolvedor: GET /v1/payment-methods é a forma mais simples de testar se a chave e o cabeçalho estão corretos. Resposta 200 significa autenticação válida.

Saques

Não existe saque no Modo Teste: com a chave de teste, POST /v1/payout-requests responde 403 com WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE. Uma chave de usuário Desenvolvedor recebe 403 com Acesso negado em saldo e saques. O acompanhamento de um saque é feito pela listagem.

Clientes

Cartões

O cartão já nasce active no cadastro, sem etapa de ativação.
POST /v1/cards registra o cartão de verdade mesmo com a chave de teste (sem cobrar), e o cofre é o mesmo para teste e produção. A cobrança com cartão salvo (POST /v1/charges com cardTokenId) é simulada no Modo Teste. Veja Credenciais e ambientes.

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 o merchantId 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.