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.

Líquidação Direta - Ambiente de Produção

O fluxo de criação de SubSellers na Marlim está disponível em produção, permitindo o cadastro completo de parceiros com todos os dados necessários para atender às diretrizes do Banco Central. No entanto, a liquidação direta para as contas bancárias dos SubSellers ainda está em desenvolvimento e não está disponível no momento. Para obter informações sobre o cronograma de disponibilização desta funcionalidade, entre em contato com o time da Marlim através dos nossos canais de suporte.

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.

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.
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.
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",
  "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"
    }
  },
}

Response Object​

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"
}

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": "2025-11-04T18:29:37.548Z",
  "date_updated": "2025-11-04T18:29:37.548Z"
}'

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.

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",
  "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": "2025-11-04T18:29:37.548Z",
  "date_updated": "2025-11-04T18:29:37.548Z",
  "business_name": "Empresa Jedi LTDA",
  "social_name": "Empresa Jedi",
  "email": "contato@empresajedi.com.br",
  "document": "12345678000190"
}