Implementar este caso com um assistente de IA
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
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
Passo a passo
Habilite o Connect e defina a configuração padrão
Crie a subconta de cada cliente
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.Conduza o KYC do cliente
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.Gere e guarde as chaves por cliente
Calcule a remuneração da agência
2 da linha tx_spread) e taxa fixa de R$ 0,50.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.Crie as cobranças pelo Órbita Pay
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.Repasse os webhooks a cada cliente
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.Ofereça saque ao cliente
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
- Mesmo grupo. As contas do
splitprecisam 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
splitenviado 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-requestsantes 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
E se a agência preferir cobrar uma mensalidade fixa?
E se a agência preferir cobrar uma mensalidade fixa?
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.E se um cliente da agência tiver vendedores próprios?
E se um cliente da agência tiver vendedores próprios?
split. A soma dos percentuais continua limitada a 100%.E se um cliente quiser Apple Pay no site dele?
E se um cliente quiser Apple Pay no site dele?
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.E se a agência quiser dar ao cliente acesso direto ao painel?
E se a agência quiser dar ao cliente acesso direto ao painel?
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 -
postbackUrlda agência em todas as cobranças - Repasse de eventos aos clientes por fila própria, com status confirmado na API
- Deduplicação por
idde evento e, nocharge.updated, por cobrança + status + data - Endpoint da conta master com
include_submerchants: truepara cobranças e saques das subcontas - Cenários de homologação de cada funcionalidade oferecida aos clientes
Como homologar
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
Chaves de API da subconta
Taxas e dados da subconta
fees-info.
