Entenda o fluxo completo de cadastro de submerchants na PayHub
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.
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.
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.
O cadastro de um submerchant segue um fluxo sequencial de etapas:
Envie os dados básicos (nome fantasia, razão social, CNPJ/CPF, e-mail, fatos transacionais). O submerchant é criado com status pending.
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.
Cadastre ao menos um endereço (faturamento, entrega ou ambos) vinculado ao submerchant.
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.
Chame POST /v1/submerchants/{id}/submit-for-review. O status muda para pending_review e a equipe PayHub avalia o cadastro.
Se aprovado, o status muda para active. Se reprovado, vá para Status e Reenvio para o fluxo request-resubmission → edição → submit-for-review.
curl -X POST https://api.payhubr.com/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": [
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.payhubr.com/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.
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.payhubr.com/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"
}'curl -X POST https://api.payhubr.com/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
}'const response = await fetch('https://api.payhubr.com/v1/submerchants', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
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: [
{
code: '4712100',
description: 'Comércio varejista de mercadorias em geral',
is_primary: true,
},
],
}),
});curl -X POST https://api.payhubr.com/v1/submerchants \
-H "Authorization: Basic {credentials}" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "pf",
"trade_name": "Maria Artesanatos",
"legal_name": "Maria da Silva",
"tax_id": "12345678901",
"email": "maria@artesanatos.com",
"phone": "11988887777",
"birth_date": "1990-05-15",
"mother_name": "Ana da Silva",
"business_type": "physical",
"product_categories": ["others-physics"],
"average_ticket": 8000,
"monthly_revenue": 150000,
"mcc": "5999"
}'const response = await fetch('https://api.payhubr.com/v1/submerchants', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify
Para pessoa física, os campos birth_date e mother_name são opcionais mas recomendados para agilizar a análise.