Visão Geral
Entenda o fluxo completo de cadastro de submerchants na SoarLabz
O que são Submerchants?
Submerchants (subcomerciantes) são entidades comerciais vinculadas ao seu merchant principal. Eles permitem que você gerencie múltiplos negócios ou vendedores sob uma única conta, cada um com seus próprios dados cadastrais, documentos e endereços.
Submerchants são ideais para marketplaces, plataformas de pagamento e qualquer modelo de negócio que envolva múltiplos vendedores.
Tipos de entidade
Submerchants podem ser cadastrados como Pessoa Jurídica (PJ) ou Pessoa Física (PF), definido pelo campo entity_type:
| Valor | Tipo | Documento esperado |
|---|---|---|
pj | Pessoa Jurídica (padrão) | CNPJ (14 dígitos) |
pf | Pessoa Física | CPF (11 dígitos) |
Se entity_type não for informado, o padrão é pj. Os documentos exigidos para análise variam conforme o tipo — veja Documentos e Endereços para detalhes.
MCC e CNAEs
Você pode informar o MCC (Merchant Category Code) e os CNAEs (Classificação Nacional de Atividades Econômicas) do submerchant. Esses dados são utilizados pelas adquirentes para classificar o tipo de negócio.
| Campo | Tipo | Descrição |
|---|---|---|
mcc | string | Código MCC de 4 dígitos (ex: "5411") |
cnaes | array | Lista de CNAEs com code, description e is_primary |
Se o mcc não for informado, o sistema tenta resolvê-lo automaticamente a partir do CNAE primário. Para PJ, é recomendado enviar ao menos um CNAE com is_primary: true.
Fluxo de Cadastro
O cadastro de um submerchant segue um fluxo sequencial de etapas:
Criar o submerchant
Envie os dados básicos (nome fantasia, razão social, CNPJ/CPF, e-mail, fatos transacionais). O submerchant é criado com status pending.
Cadastrar sócios/representantes legais (PJ)
Para submerchants do tipo PJ, adicione cada sócio/representante via POST /v1/submerchants/{id}/legal-representatives. Pelo menos um sócio é obrigatório para envio à análise.
Adicionar endereços
Cadastre ao menos um endereço (faturamento, entrega ou ambos) vinculado ao submerchant.
Adicionar documentos
Envie os documentos da empresa (PJ) e/ou pessoais. Para cada sócio (PJ), envie os documentos pessoais com legal_representative_id. Veja a lista completa em Documentos e Endereços.
Enviar para análise
Chame POST /v1/submerchants/{id}/submit-for-review. O status muda para pending_review e a equipe SoarLabz avalia o cadastro.
Ativação ou Reenvio
Se aprovado, o status muda para active. Se reprovado, vá para Status e Reenvio para o fluxo request-resubmission → edição → submit-for-review.
Exemplo Completo
1. Criar o submerchant
curl -X POST https://api.payhubrasil.com.br/v1/submerchants \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "pj",
"trade_name": "Loja do João",
"legal_name": "João Silva ME",
"tax_id": "12345678000190",
"email": "joao@lojadojoao.com",
"phone": "11999998888",
"business_type": "physical",
"product_categories": ["clothes"],
"average_ticket": 15000,
"monthly_revenue": 500000,
"mcc": "5411",
"cnaes": [
2. Cadastrar sócios e representantes legais (PJ)
Para submerchants PJ, cadastre cada sócio/representante. Repita o POST para cada pessoa — o documento (CPF/CNPJ) é a chave de idempotência.
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{submerchant_id}/legal-representatives \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"name": "João Silva",
"document": "12345678901",
"birth_date": "1985-03-20",
"phone": "11999998888",
"mother_name": "Maria Silva",
"role": "legal_representative",
"participation_percentage": 60,
"is_admin": true
}'Para PF, o representante legal não é necessário — os dados pessoais já estão no cadastro do submerchant.
3. Adicionar documentos
Envie os documentos conforme o tipo de entidade. Documentos de sócio (partner_*) devem incluir legal_representative_id. Veja a lista completa em Documentos e Endereços.
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{submerchant_id}/documents \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "social_contract",
"file_url": "https://storage.exemplo.com/docs/contrato.pdf",
"file_name": "contrato_social.pdf",
"file_size": 204800,
"mime_type": "application/pdf"
}'4. Adicionar um endereço
curl -X POST https://api.payhubrasil.com.br/v1/submerchants/{submerchant_id}/addresses \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"type": "billing",
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"city": "São Paulo",
"state": "SP",
"zip_code": "01001000",
"is_primary": true
}'