Skip to main content
POST
Esta rota cria uma subconta (SubMerchant) da Finvia vinculada à sua conta master (MerchantMaster) no Connect. É o primeiro passo para colocar um vendedor, franqueado ou parceiro para receber pagamentos dentro da sua plataforma. A subconta nasce em análise (pending) e só pode transacionar depois de aprovada no credenciamento (KYC, a verificação de identidade da empresa e dos sócios).

Quando usar

Antes de chamar

  • O módulo Connect precisa estar habilitado pela Finvia na sua conta master. Sem isso, a resposta é 403 Fast Connect not enabled..
  • Autentique com a chave secreta (sk_) da conta master (Credenciais e ambientes).
  • Pré-valide o cadastro do lojista do seu lado antes de enviar, como pedem as Regras de credenciamento.
  • Tenha em mãos os dados da empresa, do representante legal (e dos demais sócios, se houver) e da conta bancária de recebimento.
  • Os documentos (cartão CNPJ, contrato social, documento com foto e selfie) não vão nesta chamada. Eles são enviados depois, com o id devolvido aqui (Sócios e documentos).
Para o negócio: na criação, a subconta recebe uma cópia das taxas e configurações vigentes da conta master. Depois disso, as taxas da subconta são independentes: mudar as taxas da master não altera as das subcontas já criadas. As taxas de cada subconta podem ser consultadas em Taxas e dados da subconta.

Corpo da requisição

Campos obrigatórios: legalName, tradeName, companyTaxId, website, averageMonthlyRevenue, averageOrderValue, productType, legalRepresentative, contactEmail, productDescription, address, phones, bankAccount e canAccessDashboard.

Dados da empresa

Razão social. Ex.: LOJA EXEMPLO LTDA.
string
required
Nome fantasia. Ex.: Loja Exemplo.
string
required
CNPJ da empresa, com ou sem máscara. Quando address.country é BRA, precisa ser um CPF ou CNPJ com dígito verificador válido. O valor é gravado só com dígitos. Ex.: 11.222.333/0001-81.
string
required
Site da empresa (formato uri). Informe a URL onde estão os produtos ou serviços que serão vendidos: ela é conferida no credenciamento. Ex.: https://loja.exemplo.com.br.
number
required
Expectativa de faturamento médio mensal, em reais. Ex.: 30000.
number
required
Ticket médio por pedido, em reais. Ex.: 150.
string
required
Tipo de produto vendido: digital, physical ou both. Ex.: physical.
string
required
E-mail de contato da empresa. Ex.: [email protected].
string
required
Descrição curta dos produtos ou serviços. Ex.: Roupas e acessórios femininos.
string
Nome que aparece na fatura do cartão do cliente. Máximo de 40 caracteres (maxLength 40). Ex.: LOJAEXEMPLO.
object
required
Endereço da empresa. O país define as regras dos outros campos (veja a tabela abaixo).
object[]
required
Telefones da empresa.

Regras que dependem do país

Todos os campos de país da subconta usam ISO 3166-1 alpha-3: address.country, address.country do representante e dos sócios, e issuingCountry. A validação não diferencia maiúsculas de minúsculas, mas o valor é gravado como foi enviado: envie sempre em maiúsculas.
Representante legal da empresa. É sempre o representante principal da subconta (isPrimary: true), e os documentos de pessoa enviados sem indicar um sócio ficam ligados a ele.
object[]
Sócios adicionais da empresa (opcional). Cada item tem o mesmo formato do legalRepresentative, com as mesmas regras de país e de CPF. O legalRepresentative continua obrigatório e é sempre o representante legal; os adicionais são cadastrados como sócios. Os documentos dos sócios não vão neste corpo: depois da criação, use os id devolvidos em legalRepresentatives para enviar os documentos de cada sócio com token de upload.
O campo referencePoint só é gravado no endereço da empresa. No endereço próprio do representante ou de um sócio ele é aceito, mas descartado.

Conta bancária

object
required
Conta bancária da subconta. Todos os campos são obrigatórios, exceto routingNumber.
companyTaxId, idNumber (do representante e dos sócios) e bankAccount.recipientDocument são validados pelos dígitos verificadores. Os números dos exemplos desta página são válidos só para teste de formato: na sua integração, envie os documentos reais do lojista.

Acesso ao painel e notificações

boolean
required
Define se a subconta pode acessar o painel da Finvia. Ex.: true.
object
Usuário que vai acessar o painel. Obrigatório quando canAccessDashboard é true. Quando o objeto é enviado, os três campos são obrigatórios. Se o e-mail já tiver usuário cadastrado, a resposta é 400 Email already registered.
string
URL (formato uri) para receber os avisos de mudança de status da subconta. Opcional. Ex.: https://meusite.com.br/webhooks/finvia/conta.A URL fica salva nas configurações da subconta. Para alterá-la depois, fale com o suporte. Sem postbackUrl, a subconta usa a URL de aviso de status da conta master, se a master tiver uma. Esta URL não recebe eventos de cobrança. O aviso vem sem envelope, em camelCase, com merchantId, status, date e, quando o status é rejected ou correcting, rejectionReason. Veja Webhooks de conta.

Respostas

A resposta 201 traz só o id da subconta e os representantes criados. Para ver o cadastro completo, use Consultar subconta.
string
required
Identificador da subconta criada. Ex.: 36OO3bcGjhPjjF3tzrqOGcmQuKo. Guarde este valor: ele é usado para enviar documentos, consultar a subconta, obter as chaves de API e pedir saques.
Representantes criados: o representante legal primeiro (isPrimary: true) e depois os sócios adicionais, na ordem enviada. Use os id dos itens com isPrimary: false para enviar os documentos de cada sócio.
As mensagens misturam português e inglês. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição.
A criação deu certo quando a resposta é 201 com um id. A subconta começa em análise (pending) e só pode transacionar quando chegar a active.

Depois de criar

1

Envie os documentos

Use Enviar documentos para os documentos da empresa e do representante legal. Para cada sócio adicional, gere um token de upload com o id dele. A lista de documentos exigidos está em Regras de credenciamento.
2

Acompanhe a análise

Receba os avisos de status no postbackUrl e consulte a subconta com Consultar subconta. Se o status for correcting, corrija os dados ou documentos pedidos.
3

Obtenha as chaves

Com a subconta active, busque as chaves dela em Chaves de API da subconta para criar cobranças em nome do vendedor.

Exemplos por caso de uso

Vendedor que opera só pela sua plataforma. O representante usa o endereço da empresa.

Erros comuns

Veja também

Subcontas e KYC

Cadastro e credenciamento passo a passo.

Regras de credenciamento

Documentos exigidos, motivos de recusa e MCCs não aceitos.

Sócios e documentos

Documentos de cada sócio com token de upload.

Webhooks de conta

Avisos de mudança de status.