Pular para o conteúdo principal

Criar Parceiro

Para criar um parceiro, você deve utilizar essa rota.

Importante

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.

POSTv3/sub_sellers

Request Body Params

Atenção

Todos os campos do tipo string devem ser informados com caracteres alfanuméricos sem acentuação ou caracteres especiais.

Dica

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

AtributoTipoDescrição
business_namestringRazão Social da empresa. Máximo de caracteres: 30
social_namestringNome Fantasia da empresa. Máximo de caracteres: 128
emailstringE-mail da empresa.
documentstringCNPJ da empresa.
foundation_datestringData de fundação da empresa no formato YYYY-MM-DD.
automatic_anticipation_enabledbooleanParâmetro opcional que indica se o recebedor receberá antecipações automaticamente.
Default: true
annual_revenueint32Receita anual estimada da empresa
websitestringWebsite da empresa.
cnae_codestringCódigo CNAE da empresa. Deve conster apenas dígitos. Exemplo: 6201500
legal_nature_codestringCódigo da natureza jurídica da empresa. Deve conster apenas dígitos. Exemplo: 2062
company_typestringTipo de empresa. Valores aceitos: SA, LTDA, MEI, ME, EPP, EIRELI, ASSOCIACOES_ENTIDADES, DEMAIS_PORTES.
phone_numberobjectObjeto Telefone da empresa.
phone_number[country_code]stringCódigo do país do telefone da empresa (DDI), Ex: +55.
phone_number[ddd]stringDDD do telefone da empresa.
phone_number[number]stringNúmero do telefone da empresa.
main_addressobjectObjeto Endereço principal da empresa.
main_address[country]stringPaí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]stringCEP do endereço da empresa.
main_address[state]stringEstado do endereço da empresa.
main_address[city]stringCidade do endereço da empresa.
main_address[neighborhood]stringBairro do endereço da empresa.
main_address[street]stringRua do endereço da empresa.
main_address[number]stringNúmero do endereço da empresa.
main_address[complementary]stringComplemento do endereço da empresa.
managing_partnerobjectObjeto Sócio administrador da empresa.
managing_partner[name]stringNome do sócio administrador.
managing_partner[document]stringCPF do sócio administrador.
managing_partner[birthdate]stringData de nascimento do sócio administrador no formato YYYY-MM-DD.
managing_partner[email]stringEmail do sócio administrador
managing_partner[phone_number]objectObjeto Telefone do sócio administrador.
managing_partner[phone_number][country_code]stringCódigo do país do telefone do sócio administrador (DDI).
managing_partner[phone_number][ddd]stringDDD do telefone do sócio administrador.
managing_partner[phone_number][number]stringNúmero do telefone do sócio administrador.
managing_partner[address]objectObjeto Endereço do sócio administrador.
managing_partner[address][country]stringPaí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]stringCEP do endereço do sócio administrador.
managing_partner[address][state]stringEstado do endereço do sócio administrador.
managing_partner[address][city]stringCidade do endereço do sócio administrador.
managing_partner[address][neighborhood]stringBairro do endereço do sócio administrador.
managing_partner[address][street]stringRua do endereço do sócio administrador.
managing_partner[address][number]stringNúmero do endereço do sócio administrador.
managing_partner[address][complementary]stringComplemento do endereço do sócio administrador.
bank_accountobjectObjeto Conta bancária da empresa.
bank_account[bank]stringCódigo do banco.
bank_account[agency]stringNúmero da agência.
bank_account[agency_digit]stringDígito da agência.
bank_account[account_number]stringNúmero da conta.
bank_account[account_digit]stringDígito da conta.
bank_account[type]stringTipo da conta. Valores aceitos: checking ou savings.
bank_account[pix]objectObjeto de dados da chave Pix.
bank_account[pix][type]stringTipo de chave pix.
Valores aceitos: cpf, cnpj, email ou phone.
bank_account[pix][key]stringValor da chave Pix. Deve ser informado de acordo com o tipo de chave Pix.
webhook_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá informações a cada atualização do parceiro.
webhook_auth_tokenstringParâ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_statusstringParâ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.
Exemplo de Request Body
{
"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

AtributoTipoDescrição
namestringNome completo do parceiro. Mínimo de caracteres: 1
documentstringCPF do parceiro. Deve conter 11 dígitos.
emailstringE-mail do parceiro.
birthdatestringData de nascimento no formato YYYY-MM-DD.
automatic_anticipation_enabledbooleanParâmetro opcional que indica se o recebedor receberá antecipações automaticamente.
Default: true
annual_revenueint32Receita anual estimada do parceiro.
cnae_codestringParâmetro opcional. Código CNAE. Deve conter apenas dígitos. Exemplo: 7490104
legal_nature_codestringParâmetro opcional. Código da natureza jurídica. Deve conter apenas dígitos.
Exemplo: 4081
company_typestringParâmetro opcional. Tipo de empresa. Valores aceitos: SA, LTDA, MEI, ME, EPP, EIRELI, ASSOCIACOES_ENTIDADES, DEMAIS_PORTES.
Exemplo: DEMAIS_PORTES
phone_numberobjectObjeto Telefone do parceiro.
phone_number[country_code]stringCódigo do país do telefone (DDI), Ex: +55.
phone_number[ddd]stringDDD do telefone.
phone_number[number]stringNúmero do telefone.
addressobjectObjeto Endereço do parceiro.
address[country]stringPaí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]stringCEP do endereço do parceiro.
address[state]stringEstado do endereço do parceiro. Máximo em caracteres: 2
address[city]stringCidade do endereço do parceiro. Máximo em caracteres: 50
address[neighborhood]stringBairro do endereço do parceiro. Máximo em caracteres: 45
address[street]stringRua do endereço do parceiro. Máximo em caracteres: 54
address[number]stringNúmero do endereço do parceiro. Máximo em caracteres: 5
address[complementary]stringParâmetro opcional. Complemento do endereço do parceiro. Máximo em caracteres: 30
bank_accountobjectObjeto Conta bancária do parceiro.
bank_account[bank]stringCódigo do banco. Exemplo: 341
bank_account[agency]stringNúmero da agência.
bank_account[agency_digit]stringDígito da agência.
bank_account[account_number]stringNúmero da conta.
bank_account[account_digit]stringDígito da conta.
bank_account[type]stringTipo da conta. Valores aceitos: checking ou savings.
bank_account[pix]objectObjeto de dados da chave Pix.
bank_account[pix][type]stringTipo de chave pix.
Valores aceitos: cpf, cnpj, email ou phone.
bank_account[pix][key]stringValor da chave Pix. Deve ser informado de acordo com o tipo de chave Pix.
webhook_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá informações a cada atualização do parceiro.
webhook_auth_tokenstringParâ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_statusstringParâ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.
Exemplo de Request Body
{
"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

AtributoTipoDescrição
statusstringStatus do parceiro. Valor padrão: pending.
sub_seller_idstringID do parceiro.
namestringNome do parceiro.
date_createddateTimeData de criação do parceiro no formato ISODateTime.
date_updateddateTimeData de atualização do parceiro no formato ISODateTime.
business_namestringRazão Social do parceiro.
social_namestringNome Fantasia do parceiro.
emailstringE-mail do parceiro.
documentstringCNPJ do parceiro.
Exemplo de Response
{
"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

AtributoTipoDescrição
statusstringStatus do parceiro. Valor padrão: pending.
sub_seller_idstringID do parceiro.
namestringNome do parceiro.
date_createddateTimeData de criação do parceiro no formato ISODateTime.
date_updateddateTimeData de atualização do parceiro no formato ISODateTime.
emailstringE-mail do parceiro.
documentstringCPF do parceiro.
Exemplo de Response
{
"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

AtributoTipoDescrição
api_referencestringUrl para a documentação.
errorsarrayArray com todos os erros encontrados ao processar a requisição.
errors[][type]stringTipo de erro ocorrido.
errors[][message]stringMensagem detalhada do erro ocorrido.
Exemplo de erro
{
"api_reference": "https://docs.api.marlim.co/sub_sellers/create",
"errors": [
{
"type": "validation",
"message": "The CNPJ provided is invalid."
}
]
}
dica

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

Atenção

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.

StatusSignificado
activeCadastro do parceiro aprovado pela Marlim e nossa adquirente.
O parceiro está apto para realizar transações.
inactiveParceiro inativado pela Marlim ou por chamada na rota de atualizar parceiros .
Não está apto para realizar transações.
refusedCadastro do parceiro recusado pela Marlim ou nossa adquirente.
Não está apto para realizar transações
blockedO 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.
Exemplo do BODY de um WEBHOOK da Marlim para a sua aplicação
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

ATENÇÃO

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

Request
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"
}
}
}'
Response200
{
"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"
}

Criação de parceiro PF

Request
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"
}'
Response200
{
"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"
}