Skip to main content

Create Partner

To create a partner, you must use this route.

Important

In order to comply with the guidelines set forth in Central Bank Circular 3.978/20 regarding procedures to be adopted for money laundering prevention and terrorism financing, it is essential to send all the data set forth in this documentation for seller registration. This guideline came into effect in February 2024.

POSTv3/sub_sellers

Request Body Params​

Attention

All string type fields must be filled with alphanumeric characters without accents or special characters.

Tip

To find the CNAE codes (cnae_code), legal nature (legal_nature_code), and company type (company_type), you can use a free CNPJ lookup service. For example cnpja.

AttributeTypeDescription
business_namestringCompany Legal Name. Maximum characters: 30
social_namestringCompany Trade Name. Maximum characters: 128
emailstringCompany email.
documentstringCompany CNPJ.
foundation_datestringCompany foundation date in YYYY-MM-DD format.
automatic_anticipation_enabledbooleanOptional parameter indicating if the recipient will receive automatic anticipations.
Default: true
annual_revenueint32Estimated annual revenue of the company
websitestringCompany website.
cnae_codestringCompany CNAE code. Must contain only digits. Example: 6201500
legal_nature_codestringCompany legal nature code. Must contain only digits. Example: 2062
company_typestringCompany type. Accepted values: SA, LTDA, MEI, ME, EPP, EIRELI, ASSOCIACOES_ENTIDADES, DEMAIS_PORTES.
phone_numberobjectCompany Phone object.
phone_number[country_code]stringCompany phone country code (DDI), e.g.: +55.
phone_number[ddd]stringCompany phone area code.
phone_number[number]stringCompany phone number.
main_addressobjectCompany main address object.
main_address[country]stringCompany address country, in country code format. Only ISO 3166-1 alpha-2 (two-letter) format will be accepted. E.g.: BR, US, UY...
Maximum characters: 2
main_address[zip_code]stringCompany address ZIP code.
main_address[state]stringCompany address state.
main_address[city]stringCompany address city.
main_address[neighborhood]stringCompany address neighborhood.
main_address[street]stringCompany address street.
main_address[number]stringCompany address number.
main_address[complementary]stringCompany address complement.
managing_partnerobjectCompany managing partner object.
managing_partner[name]stringManaging partner name.
managing_partner[document]stringManaging partner CPF.
managing_partner[birthdate]stringManaging partner birthdate in YYYY-MM-DD format.
managing_partner[email]stringManaging partner email
managing_partner[phone_number]objectManaging partner phone object.
managing_partner[phone_number][country_code]stringManaging partner phone country code (DDI).
managing_partner[phone_number][ddd]stringManaging partner phone area code.
managing_partner[phone_number][number]stringManaging partner phone number.
managing_partner[address]objectManaging partner address object.
managing_partner[address][country]stringManaging partner address country, in country code format. Only ISO 3166-1 alpha-2 (two-letter) format will be accepted. E.g.: BR, US, UY...
Maximum characters: 2
managing_partner[address][zip_code]stringManaging partner address ZIP code.
managing_partner[address][state]stringManaging partner address state.
managing_partner[address][city]stringManaging partner address city.
managing_partner[address][neighborhood]stringManaging partner address neighborhood.
managing_partner[address][street]stringManaging partner address street.
managing_partner[address][number]stringManaging partner address number.
managing_partner[address][complementary]stringManaging partner address complement.
bank_accountobjectCompany bank account object.
bank_account[bank]stringBank code.
bank_account[agency]stringAgency number.
bank_account[agency_digit]stringAgency digit.
bank_account[account_number]stringAccount number.
bank_account[account_digit]stringAccount digit.
bank_account[type]stringAccount type. Accepted values: checking or savings.
bank_account[pix]objectPIX key data object.
bank_account[pix][type]stringPIX key type.
Accepted values: cpf, cnpj, email or phone.
bank_account[pix][key]stringPIX key value. Must be provided according to the PIX key type.
webhook_urlstringOptional parameter to pass your system's endpoint that will receive information with each partner update.
webhook_auth_tokenstringOptional parameter to authenticate notifications sent to webhook_url. If the parameter is not provided, notifications will be sent without authentication.
simulate_statusstringOptional parameter to simulate partner status in test environment, should not be sent in production.
Accepted values: active, inactive, pending, or refused.
Request Body Example
{
  "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": "Suite 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": "Apt 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"
}

Individual Partner (Person)​

AttributeTypeDescription
namestringPartner full name. Minimum characters: 1
documentstringPartner CPF. Must contain 11 digits.
emailstringPartner email.
birthdatestringBirthdate in YYYY-MM-DD format.
automatic_anticipation_enabledbooleanOptional parameter indicating if the recipient will receive automatic anticipations.
Default: true
annual_revenueint32Partner estimated annual revenue.
cnae_codestringOptional parameter. CNAE code. Must contain only digits. Example: 7490104
legal_nature_codestringOptional parameter. Legal nature code. Must contain only digits.
Example: 4081
company_typestringOptional parameter. Company type. Accepted values: SA, LTDA, MEI, ME, EPP, EIRELI, ASSOCIACOES_ENTIDADES, DEMAIS_PORTES.
Example: DEMAIS_PORTES
phone_numberobjectPartner phone object.
phone_number[country_code]stringPhone country code (DDI), e.g.: +55.
phone_number[ddd]stringPhone area code.
phone_number[number]stringPhone number.
addressobjectPartner address object.
address[country]stringPartner address country, in country code format. Only ISO 3166-1 alpha-2 (two-letter) format will be accepted. E.g.: BR, US, UY...
Maximum characters: 2
address[zip_code]stringPartner address ZIP code.
address[state]stringPartner address state. Maximum characters: 2
address[city]stringPartner address city. Maximum characters: 50
address[neighborhood]stringPartner address neighborhood. Maximum characters: 45
address[street]stringPartner address street. Maximum characters: 54
address[number]stringPartner address number. Maximum characters: 5
address[complementary]stringOptional parameter. Partner address complement. Maximum characters: 30
bank_accountobjectPartner bank account object.
bank_account[bank]stringBank code. Example: 341
bank_account[agency]stringAgency number.
bank_account[agency_digit]stringAgency digit.
bank_account[account_number]stringAccount number.
bank_account[account_digit]stringAccount digit.
bank_account[type]stringAccount type. Accepted values: checking or savings.
bank_account[pix]objectPIX key data object.
bank_account[pix][type]stringPIX key type.
Accepted values: cpf, cnpj, email or phone.
bank_account[pix][key]stringPIX key value. Must be provided according to the PIX key type.
webhook_urlstringOptional parameter to pass your system's endpoint that will receive information with each partner update.
webhook_auth_tokenstringOptional parameter to authenticate notifications sent to webhook_url. If the parameter is not provided, notifications will be sent without authentication.
simulate_statusstringOptional parameter to simulate partner status in test environment, should not be sent in production.
Accepted values: active, inactive, pending, or refused.
Request Body Example
{
  "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": "Apt 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​

AttributeTypeDescription
statusstringPartner status. Default value: pending.
sub_seller_idstringPartner ID.
namestringPartner name.
date_createddateTimePartner creation date in ISODateTime format.
date_updateddateTimePartner update date in ISODateTime format.
business_namestringPartner Legal Name.
social_namestringPartner Trade Name.
emailstringPartner email.
documentstringPartner CNPJ.
Response Example
{
  "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"
}

Individual Partner (Person)​

AttributeTypeDescription
statusstringPartner status. Default value: pending.
sub_seller_idstringPartner ID.
namestringPartner name.
date_createddateTimePartner creation date in ISODateTime format.
date_updateddateTimePartner update date in ISODateTime format.
emailstringPartner email.
documentstringPartner CPF.
Response Example
{
  "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​

AttributeTypeDescription
api_referencestringURL for documentation.
errorsarrayArray with all errors found when processing the request.
errors[][type]stringType of error that occurred.
errors[][message]stringDetailed error message.
Error Example
{
  "api_reference": "https://docs.api.marlim.co/sub_sellers/create",
  "errors": [
    {
      "type": "validation",
      "message": "The CNPJ provided is invalid."
    }
  ]
}
tip

The value returned in sub_seller_id is the ID that will be used to create transactions in Split Payment format with multiple partners and also to perform PIX transfers.

Webhook URL​

Attention

In production environment, all created partners go through a manual review process between Marlim and our Acquirer. As this is an asynchronous process, updates will be sent via webhook.

The entire partner status change process is asynchronous. Therefore, it's important that you pass a webhook_url during the partner creation process so your application receives all status changes.

If any value is passed in the webhook_auth_token parameter, Marlim will send the token to your application using the Authorization: Bearer standard in the request Header:

Authorization: Bearer {webhook_auth_token}

Below is the table with possible status values received in the webhook_url.

StatusMeaning
activePartner registration approved by Marlim and our acquirer.
The partner is able to make transactions.
inactivePartner inactivated by Marlim or by calling the update partners route.
Not able to make transactions.
refusedPartner registration refused by Marlim or our acquirer.
Not able to make transactions
blockedThe partner had their registration suspended after approval and, at the moment, is not able to make transactions. For more information, contact our support team.
Example of BODY from a WEBHOOK from Marlim to your application
curl -X POST "https://yourapplication.com/partners/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-15T17:36:12.504Z",
  "date_updated": "2026-01-15T17:36:12.504Z"
}'

Examples​

WARNING

The values used in the examples below are for illustration purposes only and should not be used to make requests to Marlim APIs. In development and testing environments, use data closer to a real transaction (card and customer data). If you use fictitious values, the Antifraud may not work as expected.

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": "Suite 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": "Apt 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-15T17:36:12.504Z",
  "date_updated": "2026-01-15T17:36:12.504Z",
  "business_name": "Empresa Jedi LTDA",
  "social_name": "Empresa Jedi",
  "email": "contato@empresajedi.com.br",
  "document": "12345678000190"
}

Individual Partner Creation​

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": "Apt 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-15T17:36:12.504Z",
  "date_updated": "2026-01-15T17:36:12.504Z",
  "email": "luke@skywalker.com",
  "document": "12345678909"
}