Criar Parceiro
Para criar um parceiro, você deve utilizar essa rota.
Com objetivo de atender as diretrizes dispostas na Circular 3.978/20 do Banco Central sobre os procedimentos a serem adotados para prevenção à lavagem de dinheiro e financiamento ao terrorismo é imprescindível o envio de todos os dados dispostos nessa documentação para o cadastro de sellers. Essa diretriz entrou em vigor em Fevereiro de 2024.
Request Body Params
Todos os campos do tipo string devem ser informados com caracteres alfanuméricos sem acentuação ou caracteres especiais.
Para buscar os códigos CNAE (cnae_code), natureza jurídica (legal_nature_code), e porte da empresa (company_type), você pode utilizar algum serviço gratuito pra consulta de cnpj. Como por exemplo o cnpja.
Parceiro Pessoa Jurídica
| Atributo | Tipo | Descrição |
|---|---|---|
| business_name | string | Razão Social da empresa. Máximo de caracteres: 30 |
| social_name | string | Nome Fantasia da empresa. Máximo de caracteres: 128 |
| string | E-mail da empresa. | |
| document | string | CNPJ da empresa. |
| foundation_date | string | Data de fundação da empresa no formato YYYY-MM-DD. |
| automatic_anticipation_enabled | boolean | Parâmetro opcional que indica se o recebedor receberá antecipações automaticamente. Default: true |
| annual_revenue | int32 | Receita anual estimada da empresa |
| website | string | Website da empresa. |
| cnae_code | string | Código CNAE da empresa. Deve conster apenas dígitos. Exemplo: 6201500 |
| legal_nature_code | string | Código da natureza jurídica da empresa. Deve conster apenas dígitos. Exemplo: 2062 |
| company_type | string | Tipo de empresa. Valores aceitos: SA, LTDA, MEI, ME, EPP, EIRELI, ASSOCIACOES_ENTIDADES, DEMAIS_PORTES. |
| phone_number | object | Objeto Telefone da empresa. |
| phone_number[country_code] | string | Código do país do telefone da empresa (DDI), Ex: +55. |
| phone_number[ddd] | string | DDD do telefone da empresa. |
| phone_number[number] | string | Número do telefone da empresa. |
| main_address | object | Objeto Endereço principal da empresa. |
| main_address[country] | string | País do endereço da empresa, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: BR, US, UY... Máximo em caracteres: 2 |
| main_address[zip_code] | string | CEP do endereço da empresa. |
| main_address[state] | string | Estado do endereço da empresa. |
| main_address[city] | string | Cidade do endereço da empresa. |
| main_address[neighborhood] | string | Bairro do endereço da empresa. |
| main_address[street] | string | Rua do endereço da empresa. |
| main_address[number] | string | Número do endereço da empresa. |
| main_address[complementary] | string | Complemento do endereço da empresa. |
| managing_partner | object | Objeto Sócio administrador da empresa. |
| managing_partner[name] | string | Nome do sócio administrador. |
| managing_partner[document] | string | CPF do sócio administrador. |
| managing_partner[birthdate] | string | Data de nascimento do sócio administrador no formato YYYY-MM-DD. |
| managing_partner[email] | string | Email do sócio administrador |
| managing_partner[phone_number] | object | Objeto Telefone do sócio administrador. |
| managing_partner[phone_number][country_code] | string | Código do país do telefone do sócio administrador (DDI). |
| managing_partner[phone_number][ddd] | string | DDD do telefone do sócio administrador. |
| managing_partner[phone_number][number] | string | Número do telefone do sócio administrador. |
| managing_partner[address] | object | Objeto Endereço do sócio administrador. |
| managing_partner[address][country] | string | País do endereço do sócio administrador, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: BR, US, UY... Máximo em caracteres: 2 |
| managing_partner[address][zip_code] | string | CEP do endereço do sócio administrador. |
| managing_partner[address][state] | string | Estado do endereço do sócio administrador. |
| managing_partner[address][city] | string | Cidade do endereço do sócio administrador. |
| managing_partner[address][neighborhood] | string | Bairro do endereço do sócio administrador. |
| managing_partner[address][street] | string | Rua do endereço do sócio administrador. |
| managing_partner[address][number] | string | Número do endereço do sócio administrador. |
| managing_partner[address][complementary] | string | Complemento do endereço do sócio administrador. |
| bank_account | object | Objeto Conta bancária da empresa. |
| bank_account[bank] | string | Código do banco. |
| bank_account[agency] | string | Número da agência. |
| bank_account[agency_digit] | string | Dígito da agência. |
| bank_account[account_number] | string | Número da conta. |
| bank_account[account_digit] | string | Dígito da conta. |
| bank_account[type] | string | Tipo da conta. Valores aceitos: checking ou savings. |
| bank_account[pix] | object | Objeto de dados da chave Pix. |
| bank_account[pix][type] | string | Tipo de chave pix. Valores aceitos: cpf, cnpj, email ou phone. |
| bank_account[pix][key] | string | Valor da chave Pix. Deve ser informado de acordo com o tipo de chave Pix. |
| webhook_url | string | Parâmetro opcional para passar o endpoint do seu sistema que receberá informações a cada atualização do parceiro. |
| webhook_auth_token | string | Parâmetro opcional para autenticar as notificações enviadas para o webhook_url. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação. |
| simulate_status | string | Parâmetro opcional para simular o status do parceiro em ambiente de testes, não deve ser enviado em produção. Valores aceitos: active, inactive, pending, ou refused. |
{
"business_name": "Empresa Jedi LTDA",
"social_name": "Empresa Jedi",
"email": "contato@empresajedi.com.br",
"document": "123456789",
"foundation_date": "2020-01-01",
"annual_revenue": 1000000000,
"website": "https://empresajedi.com.br",
"cnae_code": "6201500",
"legal_nature_code": "2062",
"company_type": "LTDA",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "999999999"
},
"main_address": {
"country": "BR",
"zip_code": "01234567",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123",
"complementary": "Sala 45"
},
"managing_partner": {
"name": "Luke Skywalker",
"document": "12345678900",
"birthdate": "1989-01-01",
"email": "luke@skywalker.com",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "988888888"
},
"address": {
"country": "BR",
"zip_code": "01234567",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123",
"complementary": "Apto 45"
}
},
"bank_account": {
"bank": "001",
"agency": "1234",
"agency_digit": "5",
"account_number": "123456",
"account_digit": "7",
"type": "checking",
"pix": {
"type": "email",
"key": "contato@empresajedi.com.br"
}
},
"webhook_url": "https://example.com/webhook",
"webhook_auth_token": "my-secret-token-123",
"simulate_status": "pending"
}
Parceiro Pessoa Física
| Atributo | Tipo | Descrição |
|---|---|---|
| name | string | Nome completo do parceiro. Mínimo de caracteres: 1 |
| document | string | CPF do parceiro. Deve conter 11 dígitos. |
| string | E-mail do parceiro. | |
| birthdate | string | Data de nascimento no formato YYYY-MM-DD. |
| automatic_anticipation_enabled | boolean | Parâmetro opcional que indica se o recebedor receberá antecipações automaticamente. Default: true |
| annual_revenue | int32 | Receita anual estimada do parceiro. |
| cnae_code | string | Parâmetro opcional. Código CNAE. Deve conter apenas dígitos. Exemplo: 7490104 |
| legal_nature_code | string | Parâmetro opcional. Código da natureza jurídica. Deve conter apenas dígitos. Exemplo: 4081 |
| company_type | string | Parâmetro opcional. Tipo de empresa. Valores aceitos: SA, LTDA, MEI, ME, EPP, EIRELI, ASSOCIACOES_ENTIDADES, DEMAIS_PORTES. Exemplo: DEMAIS_PORTES |
| phone_number | object | Objeto Telefone do parceiro. |
| phone_number[country_code] | string | Código do país do telefone (DDI), Ex: +55. |
| phone_number[ddd] | string | DDD do telefone. |
| phone_number[number] | string | Número do telefone. |
| address | object | Objeto Endereço do parceiro. |
| address[country] | string | País do endereço do parceiro, no formato sigla do país. Só serão aceitos o formato ISO 3166-1 alfa-2 (duas-letras) Ex: BR, US, UY... Máximo em caracteres: 2 |
| address[zip_code] | string | CEP do endereço do parceiro. |
| address[state] | string | Estado do endereço do parceiro. Máximo em caracteres: 2 |
| address[city] | string | Cidade do endereço do parceiro. Máximo em caracteres: 50 |
| address[neighborhood] | string | Bairro do endereço do parceiro. Máximo em caracteres: 45 |
| address[street] | string | Rua do endereço do parceiro. Máximo em caracteres: 54 |
| address[number] | string | Número do endereço do parceiro. Máximo em caracteres: 5 |
| address[complementary] | string | Parâmetro opcional. Complemento do endereço do parceiro. Máximo em caracteres: 30 |
| bank_account | object | Objeto Conta bancária do parceiro. |
| bank_account[bank] | string | Código do banco. Exemplo: 341 |
| bank_account[agency] | string | Número da agência. |
| bank_account[agency_digit] | string | Dígito da agência. |
| bank_account[account_number] | string | Número da conta. |
| bank_account[account_digit] | string | Dígito da conta. |
| bank_account[type] | string | Tipo da conta. Valores aceitos: checking ou savings. |
| bank_account[pix] | object | Objeto de dados da chave Pix. |
| bank_account[pix][type] | string | Tipo de chave pix. Valores aceitos: cpf, cnpj, email ou phone. |
| bank_account[pix][key] | string | Valor da chave Pix. Deve ser informado de acordo com o tipo de chave Pix. |
| webhook_url | string | Parâmetro opcional para passar o endpoint do seu sistema que receberá informações a cada atualização do parceiro. |
| webhook_auth_token | string | Parâmetro opcional para autenticar as notificações enviadas para o webhook_url. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação. |
| simulate_status | string | Parâmetro opcional para simular o status do parceiro em ambiente de testes, não deve ser enviado em produção. Valores aceitos: active, inactive, pending, ou refused. |
{
"name": "Luke Skywalker",
"document": "12345678909",
"email": "luke@skywalker.com",
"birthdate": "1985-03-15",
"automatic_anticipation_enabled": true,
"annual_revenue": 120000,
"cnae_code": "7490104",
"legal_nature_code": "4081",
"company_type": "DEMAIS_PORTES",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "987654321"
},
"address": {
"country": "BR",
"zip_code": "01310100",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Avenida Paulista",
"number": "1000",
"complementary": "Apto 45"
},
"bank_account": {
"bank": "341",
"agency": "1234",
"agency_digit": "5",
"account_number": "123456",
"account_digit": "7",
"type": "checking",
"pix": {
"type": "cpf",
"key": "12345678909"
}
},
"webhook_url": "https://example.com/webhook",
"webhook_auth_token": "my-secret-token-123",
"simulate_status": "pending"
}
Response Object
Parceiro Pessoa Jurídica
| Atributo | Tipo | Descrição |
|---|---|---|
| status | string | Status do parceiro. Valor padrão: pending. |
| sub_seller_id | string | ID do parceiro. |
| name | string | Nome do parceiro. |
| date_created | dateTime | Data de criação do parceiro no formato ISODateTime. |
| date_updated | dateTime | Data de atualização do parceiro no formato ISODateTime. |
| business_name | string | Razão Social do parceiro. |
| social_name | string | Nome Fantasia do parceiro. |
| string | E-mail do parceiro. | |
| document | string | CNPJ do parceiro. |
{
"status": "pending",
"sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
"name": "Empresa Jedi",
"date_created": "2025-07-07T19:26:42.779Z",
"date_updated": "2025-07-07T20:26:42.779Z",
"business_name": "Empresa Jedi LTDA",
"social_name": "Empresa Jedi",
"email": "contato@empresajedi.com.br",
"document": "12345678000190"
}
Parceiro Pessoa Física
| Atributo | Tipo | Descrição |
|---|---|---|
| status | string | Status do parceiro. Valor padrão: pending. |
| sub_seller_id | string | ID do parceiro. |
| name | string | Nome do parceiro. |
| date_created | dateTime | Data de criação do parceiro no formato ISODateTime. |
| date_updated | dateTime | Data de atualização do parceiro no formato ISODateTime. |
| string | E-mail do parceiro. | |
| document | string | CPF do parceiro. |
{
"status": "pending",
"sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
"name": "Luke Skywalker",
"date_created": "2025-07-07T19:26:42.779Z",
"date_updated": "2025-07-07T20:26:42.779Z",
"email": "luke@skywalker.com",
"document": "12345678909"
}
Error Object
| Atributo | Tipo | Descrição |
|---|---|---|
| api_reference | string | Url para a documentação. |
| errors | array | Array com todos os erros encontrados ao processar a requisição. |
| errors[][type] | string | Tipo de erro ocorrido. |
| errors[][message] | string | Mensagem detalhada do erro ocorrido. |
{
"api_reference": "https://docs.api.marlim.co/sub_sellers/create",
"errors": [
{
"type": "validation",
"message": "The CNPJ provided is invalid."
}
]
}
O valor retornado em sub_seller_id é o ID que será usado para criar transações no formato Split Pagamento com múltiplos parceiros e também para realizar o repasse do Pix.
Webhook URL
Em ambiente produção, todos os parceiros criados passam por um processo de análise manual entre a Marlim e nosso Adquirente. Por se tratar de um processo assíncrono, as atualizações serão enviadas via webhook.
Todo o processo de mudança de status de um parceiro é assíncrono. Por isso, é importante que você passe um webhook_url durante o processo de criação de um parceiro para que sua aplicação receba todas as mudanças de status.
Se for passado algum valor no parâmetro webhook_auth_token a Marlim vai enviar o token para a sua aplicação usando o padrão Authorization: Bearer no Header da requisição:
Authorization: Bearer {webhook_auth_token}
Abaixo, a tabela com os valores possíveis de status recebidos no webhook_url.
| Status | Significado |
|---|---|
active | Cadastro do parceiro aprovado pela Marlim e nossa adquirente. O parceiro está apto para realizar transações. |
inactive | Parceiro inativado pela Marlim ou por chamada na rota de atualizar parceiros . Não está apto para realizar transações. |
refused | Cadastro do parceiro recusado pela Marlim ou nossa adquirente. Não está apto para realizar transações |
blocked | O parceiro teve o cadastro suspenso após a aprovação e, no momento, não está apto a realizar transações. Para mais informações, entre em contato com nossa equipe de suporte. |
curl -X POST "https://suaaplicacao.com.br/parceiros/123456789/webhook" \
-H "Content-Type: application/json" \
-H "User-Agent: Marlim/1.0.0" \
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-d '{
"event": "sub_seller_status_update",
"status": "active",
"sub_seller_id": "sub_n5yn9vci3yi8tr0gptsa2tvc6",
"date_created": "2026-01-13T14:15:06.778Z",
"date_updated": "2026-01-13T14:15:06.778Z"
}'
Exemplos
Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim. Em ambiente de desenvolvimento e testes, utilize dados mais próximos de uma transação real (dados de cartão e cliente). Se você utilizar valores fictícios o Antifraude pode não funcionar de forma esperada.
Criação de parceiro PJ
- Parceiro Criado com Sucesso
- Faltando Parâmetros
- CNPJ Inválido
curl -X POST "https://api.marlim.co/v3/sub_sellers" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"business_name": "Empresa Jedi LTDA",
"social_name": "Empresa Jedi",
"email": "contato@empresajedi.com.br",
"document": "12345678000190",
"foundation_date": "2020-01-01",
"annual_revenue": 1000000000,
"website": "https://empresajedi.com.br",
"cnae_code": "6201500",
"legal_nature_code": "2062",
"company_type": "LTDA",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "999999999"
},
"main_address": {
"country": "BR",
"zip_code": "01234567",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123",
"complementary": "Sala 45"
},
"managing_partner": {
"name": "Luke Skywalker",
"document": "12345678900",
"birthdate": "1989-01-01",
"email": "luke@skywalker.com",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "988888888"
},
"address": {
"country": "BR",
"zip_code": "01234567",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123",
"complementary": "Apto 45"
}
},
"bank_account": {
"bank": "001",
"agency": "1234",
"agency_digit": "5",
"account_number": "123456",
"account_digit": "7",
"type": "checking",
"pix": {
"type": "email",
"key": "contato@empresajedi.com.br"
}
}
}'
{
"status": "pending",
"sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
"name": "Empresa Jedi",
"date_created": "2026-01-13T14:15:06.778Z",
"date_updated": "2026-01-13T14:15:06.778Z",
"business_name": "Empresa Jedi LTDA",
"social_name": "Empresa Jedi",
"email": "contato@empresajedi.com.br",
"document": "12345678000190"
}
curl -X POST "https://api.marlim.co/v3/sub_sellers" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"business_name": "Empresa Jedi LTDA",
"social_name": "Empresa Jedi",
"email": "contato@empresajedi.com.br",
"document": "12345678000190",
"foundation_date": "2020-01-01",
"cnae_code": "6201500",
"legal_nature_code": "2062",
"company_type": "LTDA",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "999999999"
},
"main_address": {
"zip_code": "01234567",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123"
},
"managing_partner": {
"name": "Luke Skywalker",
"document": "12345678900",
"birthdate": "1989-01-01",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "988888888"
}
}
}'
{
"api_reference": "https://docs.api.marlim.co/sub_sellers/create",
"errors": [
{
"type": "parameter",
"message": "The parameter [ bank_account ] is missing."
}
]
}
curl -X POST "https://api.marlim.co/v3/sub_sellers" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"business_name": "Empresa Jedi LTDA",
"social_name": "Empresa Jedi",
"email": "contato@empresajedi.com.br",
"document": "123456789",
"foundation_date": "2020-01-01",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "999999999"
},
"main_address": {
"zip_code": "01234567",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123",
"complementary": "Sala 45"
},
"managing_partner": {
"name": "Luke Skywalker",
"document": "12345678900",
"birthdate": "1989-01-01",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "988888888"
},
"address": {
"zip_code": "01234567",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123",
"complementary": "Apto 45"
}
},
"bank_account": {
"bank": "001",
"agency": "1234",
"agency_digit": "5",
"account_number": "123456",
"account_digit": "7",
"type": "checking",
"pix": {
"type": "email",
"key": "contato@empresajedi.com.br"
}
}
}'
{
"api_reference": "https://docs.api.marlim.co/sub_sellers/create",
"errors": [
{
"type": "validation",
"message": "The CNPJ provided is invalid."
}
]
}
Criação de parceiro PF
- Parceiro Criado com Sucesso
- Faltando Parâmetros
- CPF Inválido
curl -X POST "https://api.marlim.co/v3/sub_sellers" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"name": "Luke Skywalker",
"document": "12345678909",
"email": "luke@skywalker.com",
"birthdate": "1985-03-15",
"automatic_anticipation_enabled": true,
"annual_revenue": 120000,
"cnae_code": "7490104",
"legal_nature_code": "4081",
"company_type": "DEMAIS_PORTES",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "987654321"
},
"address": {
"country": "BR",
"zip_code": "01310100",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Avenida Paulista",
"number": "1000",
"complementary": "Apto 45"
},
"bank_account": {
"bank": "341",
"agency": "1234",
"agency_digit": "5",
"account_number": "123456",
"account_digit": "7",
"type": "checking",
"pix": {
"type": "cpf",
"key": "12345678909"
}
},
"webhook_url": "https://example.com/webhook",
"webhook_auth_token": "my-secret-token-123"
}'
{
"status": "pending",
"sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
"name": "Luke Skywalker",
"date_created": "2026-01-13T14:15:06.778Z",
"date_updated": "2026-01-13T14:15:06.778Z",
"email": "luke@skywalker.com",
"document": "12345678909"
}
curl -X POST "https://api.marlim.co/v3/sub_sellers" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"name": "Luke Skywalker",
"document": "12345678909",
"email": "luke@skywalker.com",
"birthdate": "1985-03-15",
"automatic_anticipation_enabled": true,
"annual_revenue": 120000,
"cnae_code": "7490104",
"legal_nature_code": "4081",
"company_type": "DEMAIS_PORTES",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "999999999"
},
"address": {
"zip_code": "01234567",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Rua Jedi",
"number": "123"
}
}'
{
"api_reference": "https://docs.api.marlim.co/sub_sellers/create",
"errors": [
{
"type": "parameter",
"message": "The parameter [ bank_account ] is missing."
}
]
}
curl -X POST "https://api.marlim.co/v3/sub_sellers" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"name": "Luke Skywalker",
"document": "123456789090",
"email": "luke@skywalker.com",
"birthdate": "1985-03-15",
"automatic_anticipation_enabled": true,
"annual_revenue": 120000,
"cnae_code": "7490104",
"legal_nature_code": "4081",
"company_type": "DEMAIS_PORTES",
"phone_number": {
"country_code": "+55",
"ddd": "11",
"number": "987654321"
},
"address": {
"country": "BR",
"zip_code": "01310100",
"state": "SP",
"city": "Sao Paulo",
"neighborhood": "Centro",
"street": "Avenida Paulista",
"number": "1000",
"complementary": "Apto 45"
},
"bank_account": {
"bank": "341",
"agency": "1234",
"agency_digit": "5",
"account_number": "123456",
"account_digit": "7",
"type": "checking",
"pix": {
"type": "cpf",
"key": "12345678909"
}
},
"webhook_url": "https://example.com/webhook",
"webhook_auth_token": "my-secret-token-123"
}'
{
"api_reference": "https://docs.api.marlim.co/sub_sellers/create",
"errors": [
{
"type": "validation",
"message": "The CPF provided is invalid."
}
]
}