Skip to main content
Agências digitais e plataformas de tecnologia muitas vezes querem oferecer pagamentos aos clientes com a própria marca: o cliente da agência integra uma vez, vê a marca da agência e não precisa negociar diretamente com um gateway. Esta página mostra como montar essa camada sobre a API da Finvia, com uma subconta para cada cliente, a remuneração da agência separada em cada venda e os avisos de pagamento repassados a cada cliente.
Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em Integrar com IA.

Implementar este caso com um assistente de IA

Open in Cursor

O cenário

A Órbita Digital é uma agência de Florianópolis que cria e mantém lojas virtuais e sistemas de agendamento para 60 clientes: lojas de moda, restaurantes, clínicas de estética e escolas de idiomas. A Órbita quer lançar o Órbita Pay, uma camada de pagamentos própria:
  • o sistema de cada cliente fala só com a API do Órbita Pay;
  • o dinheiro de cada venda entra na conta do cliente;
  • a Órbita recebe 1,5% do valor bruto de cada venda;
  • cada cliente recebe os avisos de pagamento no sistema dele;
  • a Órbita vê as taxas de cada cliente para montar a proposta comercial.

O que a Finvia resolve

Para o negócio: com o Connect, a Órbita vira a conta master (MerchantMaster) e cada cliente vira uma subconta (SubMerchant), com cadastro, análise de documentos, chaves de API e saldo próprios. O backend do Órbita Pay cria as cobranças com a chave da subconta do cliente, então o dinheiro entra no saldo do cliente. O campo split separa a remuneração da Órbita em cada venda. A Órbita recebe os eventos de cobrança e repassa a cada cliente. A rota de taxas mostra as taxas cadastradas de cada subconta.

Arquitetura da solução

O desenho abaixo mostra uma venda feita pelo Órbita Pay, do sistema do cliente até o repasse do aviso de pagamento. Este segundo desenho mostra a estrutura de contas: a Órbita é a conta master e cada cliente tem a própria subconta. Todo cliente segue o mesmo desenho do Bistrô Maré: recebe as vendas no próprio saldo e saca por Pix para a chave CNPJ dele.

Passo a passo

1

Habilite o Connect e defina a configuração padrão

A Finvia habilita o módulo na conta da Órbita. Na criação, cada subconta recebe uma cópia das taxas e configurações da conta master vigentes naquele momento. Depois disso, as taxas da subconta são independentes: mudar as taxas da conta master não muda as das subcontas já criadas. Antes de cadastrar o primeiro cliente, alinhe com o time Finvia as taxas e a configuração que a conta master vai ter, porque elas viram o ponto de partida de todas as subcontas.
2

Crie a subconta de cada cliente

Quando a Órbita fecha com um cliente novo, o Bistrô Maré, o backend do Órbita Pay cria a subconta com a chave da conta master. O corpo segue o mesmo formato mostrado em Marketplace e PSP: dados da empresa, productType, representante legal, endereço, telefones, conta bancária e canAccessDashboard. Com país BRA, a API confere o dígito verificador do CNPJ e do CPF do responsável, a UF e o CEP de 8 dígitos, e o addressLine1 leva o número depois da vírgula (Av. Paulista, 1000). Um CNPJ que já existe entre as subcontas da Órbita é recusado com 409.Com canAccessDashboard: true, o cliente ganha acesso ao painel da Finvia e o objeto user passa a ser obrigatório. Com false, o cliente usa só as telas do Órbita Pay. A decisão é da agência e depende de quanto ela quer centralizar o atendimento.Guarde o id da subconta junto do cadastro do cliente no Órbita Pay.
3

Conduza o KYC do cliente

Envie cartão CNPJ, contrato social, documento do responsável (frente e verso) e selfie com documento. Se preferir que o próprio cliente envie os arquivos, emita um token de upload (POST /v1/submerchants/{merchantId}/document/upload-token, válido por 300 segundos e de uso único) e deixe o navegador do cliente chamar POST /v1/document-uploads com Authorization: Bearer. Assim, a chave da agência não sai do servidor.Acompanhe os avisos de status até active. Eles vão para o postbackUrl informado na criação da subconta (sem ele, para a URL de aviso da conta master, se houver). Quando vier correcting ou rejected, o motivo está em rejectionReason. A correção de dados é feita no painel da Finvia, na gestão de subcontas.
4

Gere e guarde as chaves por cliente

Com a subconta ativa:
A chave secreta do cliente fica no backend do Órbita Pay, em um cofre de segredos, associada ao cliente. O sistema do cliente recebe uma credencial da própria Órbita, emitida pela agência. A chave pública pode ir para o front-end do cliente quando ele usar Apple Pay ou 3D Secure; ela não cria cobranças. As duas chaves formam um par: se a secreta for trocada, a pública também muda.
Não entregue a chave secreta da Finvia ao cliente se o modelo é que todas as chamadas passem pela Órbita. Com a chave na mão, o cliente pode criar cobranças sem o split da agência.
5

Calcule a remuneração da agência

A Órbita quer 1,5% do valor bruto. O split incide sobre o valor líquido: o valor da venda menos a taxa transacional (fixa mais percentual). Exemplo com números ilustrativos: venda de R$ 180,00 em 3x, com taxa transacional de 3,99% (índice 2 da linha tx_spread) e taxa fixa de R$ 0,50.A taxa de antecipação (2,50% ao mês no exemplo abaixo) não entra nessa conta. Ela só reduz a base quando o cliente antecipa o recebível: nesse caso, o split é recalculado sobre o valor antecipado e a Órbita recebe proporcionalmente menos. A taxa de antecipação é mensal, multiplicada pelo número de meses até o vencimento de cada parcela (mínimo de 1 mês).As taxas reais de cada cliente vêm da rota de taxas, chamada com a chave da conta master:
Com a chave da conta master, a rota devolve a subconta pedida. Com a chave da própria subconta, ela ignora o id e devolve os dados da subconta autenticada. Um id que não pertence à Órbita retorna 404 “Subconta não encontrada”; sem o Connect habilitado, 403. Escolher a linha certa por bandeira e parcela é responsabilidade de quem consome: use a linha da bandeira do cartão quando existir e a linha brand: null quando não houver. A rota não traz reserva financeira nem taxa de saque.Lista fees vazia, ou sem linha para o método e a moeda, significa subconta sem taxas configuradas: as cobranças dessa combinação são recusadas com 422 Fees not configured. Nesse caso, acione o suporte da Finvia.
6

Crie as cobranças pelo Órbita Pay

O sistema do cliente chama a API do Órbita Pay. O backend da Órbita recebe o pedido, calcula o percentual e chama a Finvia com a chave da subconta do cliente:
O merchantId do split é o ID da conta master da Órbita (36OO3bcGjhPjjF3tzrqOGcmQuKo). Nos exemplos desta página, 2vorkLm4Qp8TzR1sXc7Yb3NdWkE é a subconta do Bistrô Maré. O restante do líquido fica com o Bistrô Maré, que é o originador da venda. A parte da Órbita é repassada quando o recebível do Bistrô Maré é liquidado: no cartão, a cada parcela, em D+30, D+60 e D+90; no Pix, logo após a confirmação do pagamento.
7

Repasse os webhooks a cada cliente

As cobranças pertencem às subcontas dos clientes. Para receber os eventos de todas elas, a Órbita cadastra um endpoint na conta master com a opção de incluir subcontas:
O corpo vai em snake_case, e enabled_events: [] significa todos os eventos. A resposta é 201 sem corpo; para obter o id do endpoint, use GET /v1/webhook-endpoints?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo. No painel, o mesmo cadastro fica em Configurações > Webhooks, com a opção de incluir subcontas. O postbackUrl de todas as cobranças também aponta para o Órbita Pay, em outra URL.Ao receber um evento, a Órbita identifica o cliente pelo merchant_id do evento (ou pelo metadata), confirma o status na Finvia e repassa ao endpoint que o cliente cadastrou no Órbita Pay.
Para o desenvolvedor: responda à Finvia com 200 antes de repassar ao cliente, e faça o repasse por uma fila com retentativa própria. Se o endpoint do cliente estiver fora do ar, a fila da Órbita tenta de novo, sem depender de uma nova entrega da Finvia. Como o charge.updated não tem id, use o data.id da cobrança mais o status e o updatedAt para deduplicar.
8

Ofereça saque ao cliente

Cada cliente saca o próprio saldo por Pix para a chave CNPJ da subconta, com valor em reais e mínimo de R$ 1,00. A Órbita pede o saque com a chave secreta da conta master:
O saque nasce pending, passa por aprovação da Finvia e termina approved ou rejected. Os avisos payout.approved e payout.rejected chegam ao endpoint da conta master com a opção de incluir subcontas, com os valores em texto decimal ("1200.00000000"). Confirme o status pela listagem GET /v1/payout-requests?merchantId=2vorkLm4Qp8TzR1sXc7Yb3NdWkE antes de avisar o cliente. Oriente cada cliente a cadastrar o CNPJ como chave Pix em uma conta bancária da empresa antes do primeiro saque.

Regras e cuidados

Uma chave por cliente, sempre a certa. Cobrança criada com a chave da conta master fica no saldo da Órbita. Cobrança criada com a chave de outro cliente fica no saldo do cliente errado. Valide o mapeamento cliente → chave antes de cada chamada.
Valores em reais em cobrança, split e saque. "amount": 180 é R$ 180,00.
  • Mesmo grupo. As contas do split precisam pertencer ao mesmo grupo Connect (a conta master e as subcontas dela). A soma dos percentuais não passa de 100%.
  • Split da requisição prevalece. O split enviado na cobrança vale para aquela venda e prevalece sobre a regra padrão de split da conta.
  • Assinaturas sem split. Se um cliente cobrar mensalidades por assinatura, essas cobranças recorrentes não recebem split e a remuneração da Órbita não sai automaticamente.
  • Webhooks sem assinatura. Os eventos não têm assinatura HMAC (Webhooks): confirme o status na API antes de repassar ao cliente um evento que libera produto ou serviço.
  • Saques pela listagem. Confirme o status de cada saque em GET /v1/payout-requests antes de avisar o cliente.
  • Homologação por funcionalidade. Cada funcionalidade que a Órbita oferece (cartão, Pix, Apple Pay, split, subcontas, saques) tem cenários próprios no roteiro. O roteiro é uma etapa recomendada, acompanhada pelo suporte da Finvia; a API não bloqueia a produção até a homologação.

Variações do caso

Remova o split das cobranças dos clientes e cobre a mensalidade da agência como uma assinatura na conta master, com o cliente da agência como pagador. O desenho está em SaaS por assinatura.
Subconta e conta master formam um único nível no Connect. Se o cliente for um marketplace com vendedores, os vendedores podem ser subcontas no mesmo grupo da Órbita, e a venda pode separar a parte do marketplace (subconta para subconta) e a parte da Órbita (subconta para conta master) no mesmo split. A soma dos percentuais continua limitada a 100%.
O domínio do checkout precisa ser registrado com a chave secreta da subconta do cliente (POST /v1/apple-pay/domains). Registrar o primeiro domínio ativa o Apple Pay na subconta, e o registro vale para teste e produção. Plataformas que servem várias lojas no mesmo hostname registram esse hostname uma vez para cada merchant. A validação de sessão no navegador usa a chave pública da subconta. Detalhes no guia de Apple Pay.
Crie a subconta com canAccessDashboard: true e o objeto user (nome, e-mail e telefone no formato E.164). O cliente passa a ver as próprias movimentações no painel da Finvia.

Checklist de implementação

  • Connect habilitado e configuração padrão da conta master alinhada com a Finvia
  • Criação de subconta por cliente, com KYC completo
  • Token de upload para o cliente enviar documentos sem expor a chave da agência
  • Tratamento dos avisos de status das subcontas
  • Chaves secretas dos clientes em cofre de segredos, no backend da agência
  • Mapeamento cliente → subconta → chave validado antes de cada cobrança
  • Percentual do split calculado por venda com as taxas de fees-info
  • postbackUrl da agência em todas as cobranças
  • Repasse de eventos aos clientes por fila própria, com status confirmado na API
  • Deduplicação por id de evento e, no charge.updated, por cobrança + status + data
  • Endpoint da conta master com include_submerchants: true para cobranças e saques das subcontas
  • Cenários de homologação de cada funcionalidade oferecida aos clientes

Como homologar

Cada cenário pede evidência (requisição, resposta, id e registro de webhook), enviada ao suporte da Finvia, que acompanha a homologação. O saque (FC-07) não roda com a chave de teste, que recebe 403 WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE. Detalhes no roteiro de homologação e no checklist de go-live.

Veja também

Connect

Conta master, subcontas e cópia das configurações na criação.

Chaves de API da subconta

Referência da rota de chaves.

Taxas e dados da subconta

Referência da rota fees-info.

Webhooks

Canais, envelopes e retentativas.