Visão Geral

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 Accithus 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

Pessoa Jurídica (PJ)
Pessoa Física (PF)

curl -X POST https://api.accithus.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": "[email protected]",
    "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
      }
    ]
  }'

const response = await fetch('https://api.accithus.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: '[email protected]',
    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.accithus.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": "[email protected]",
    "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.accithus.com/v1/submerchants', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entity_type: 'pf',
    trade_name: 'Maria Artesanatos',
    legal_name: 'Maria da Silva',
    tax_id: '12345678901',
    email: '[email protected]',
    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',
  }),
});

Para pessoa física, os campos birth_date e mother_name são opcionais mas recomendados para agilizar a análise.

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.accithus.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.

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.accithus.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"
  }'

4. Adicionar um endereço

curl -X POST https://api.accithus.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
  }'

Próximos Passos

Documentos e Endereços

Detalhes sobre tipos de documentos e gerenciamento de endereços.

Status e Reenvio

Ciclo de vida do submerchant e como tratar rejeições.

Configuração de Split

Como configurar a divisão de pagamentos entre merchant e submerchants.

Começando

Cobranças

Submerchants

Financeiro

Configuração

SDK de Segurança

Webhooks

O que são Submerchants?

Tipos de entidade

MCC e CNAEs

Fluxo de Cadastro

Exemplo Completo

1. Criar o submerchant

2. Cadastrar sócios e representantes legais (PJ)

3. Adicionar documentos

4. Adicionar um endereço

Próximos Passos

Documentos e Endereços

Status e Reenvio

Configuração de Split

​O que são Submerchants?

​Tipos de entidade

​MCC e CNAEs

​Fluxo de Cadastro

​Exemplo Completo

​1. Criar o submerchant

​2. Cadastrar sócios e representantes legais (PJ)

​3. Adicionar documentos

​4. Adicionar um endereço

​Próximos Passos

Documentos e Endereços

Status e Reenvio

Configuração de Split

O que são Submerchants?

Tipos de entidade

MCC e CNAEs

Fluxo de Cadastro

Exemplo Completo

1. Criar o submerchant

2. Cadastrar sócios e representantes legais (PJ)

3. Adicionar documentos

4. Adicionar um endereço

Próximos Passos