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.

Payout Settings​

Attention

To send the anticipation_settings parameter, prior enablement by Marlim is required. Contact our support for more information.

The fields below are optional and control the partner's financial flow, that is, how and when they receive the transaction amounts. They apply to both Legal Entity and Individual partners.

  • automatic_anticipation_enabled (boolean, default true): indicates whether the partner's receivables are automatically anticipated. When true, credit sales are anticipated according to the term defined in anticipation_settings.
  • automatic_withdrawal (boolean, default true): indicates whether the available balance is automatically transferred to the partner's registered bank account. When false, the balance remains held in the partner's account until the transfer is manually requested.
  • anticipation_settings (enum, default D1): defines how many days after the transaction the receivables become available for transfer. See the meaning of each option in the table below. Requires prior enablement.
ValueAvailability periodMeaning in the financial flow
D11 day after the transactionReceivables are anticipated and become available for transfer 1 day after the transaction is captured. It is the shortest receiving period.
D55 days after the transactionReceivables become available for transfer 5 days after the transaction is captured.
D77 days after the transactionReceivables become available for transfer 7 days after the transaction is captured.
D1010 days after the transactionReceivables become available for transfer 10 days after the transaction is captured.
D1515 days after the transactionReceivables become available for transfer 15 days after the transaction is captured.
D2222 days after the transactionReceivables become available for transfer 22 days after the transaction is captured.
D3030 days after the transactionReceivables become available for transfer 30 days after the transaction is captured.
timelineAccording to the receivables' original scheduleThere is no automatic anticipation: each installment is made available on its natural settlement date (installment-by-installment flow). Requires prior enablement by Marlim — contact support.
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
automatic_withdrawalbooleanOptional parameter indicating if the recipient will receive receivable transfers automatically.
Default: true
anticipation_settingsenumAnticipation setting. Accepted values: D1, D5, D7, D10, D15, D22, D30, timeline.
Default: D1
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[mother_name]stringManaging partner mother name.
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.
Exemplo: 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, phone or random.
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.
metadataobjectOptional parameter to pass additional partner data.
metadata[description]stringDescription of the partner's business activity. Maximum characters: 200.
Request Body Example
{
  "business_name": "Empresa Jedi LTDA",
  "social_name": "Empresa Jedi",
  "email": "contato@empresajedi.com.br",
  "document": "123456789",
  "foundation_date": "2020-01-01",
  "automatic_anticipation_enabled": true,
  "automatic_withdrawal": true,
  "anticipation_settings": "D1",
  "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",
    "mother_name": "Padmé Amidala",
    "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",
  "metadata": {
    "description": "Prestação de serviços de segurança, defesa e mediação de conflitos intergalácticos."
  }
}

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
automatic_withdrawalbooleanOptional parameter indicating if the recipient will receive receivable transfers automatically.
Default: true
anticipation_settingsenumAnticipation setting. Accepted values: D1, D5, D7, D10, D15, D22, D30, timeline.
Default: D1
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
mother_namestringPartner's mother name.
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]stringCódigo do banco.
Ex: 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, phone or random.
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.
metadataobjectOptional parameter to pass additional partner data.
metadata[description]stringDescription of the partner's business activity. Maximum characters: 200.
Request Body Example
{
  "name": "Luke Skywalker",
  "document": "12345678909",
  "email": "luke@skywalker.com",
  "birthdate": "1985-03-15",
  "automatic_anticipation_enabled": true,
  "automatic_withdrawal": true,
  "anticipation_settings": "D1",
  "annual_revenue": 120000,
  "cnae_code": "7490104",
  "legal_nature_code": "4081",
  "company_type": "DEMAIS_PORTES",
  "mother_name": "Padmé Amidala",
  "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",
  "metadata": {
    "description": "Administração pública, diplomacia e relações governamentais."
  }
}

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}

Partner Status​

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-08-07T15:40:06.997Z",
  "date_updated": "2026-08-07T15:40:06.997Z"
}'

PIX Registration Status​

For sellers that use PIX, the webhook will contain the following fields:

  • pix_url_kyp with the URL to perform the KYP process with our PIX partner.
  • pix_status with the status of the PIX registration validation process with our PIX partner.

Below is the table with possible status values received in the pix_status field. They only affect PIX transactions.

StatusMeaning
pendingThe PIX registration validation process is pending and the partner is not able to make PIX transactions.
activeThe PIX registration validation process was approved and the partner is able to make PIX transactions.
inactivePartner temporarily inactivated. Not able to make PIX transactions.
refusedThe PIX registration validation process was rejected and the partner is not able to make PIX transactions.
blockedThe partner had their registration suspended after approval and, at the moment, is not able to make PIX 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-08-07T15:40:06.997Z",
  "date_updated": "2026-08-07T15:40:06.997Z",
  "pix_url_kyp": "https://pix.com.br/1234567890",
  "pix_status": "pending"
}'

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",
  "automatic_anticipation_enabled": true,
  "automatic_withdrawal": true,
  "anticipation_settings": "D1",
  "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",
    "mother_name": "Padmé Amidala",
    "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"
    }
  },
  "webhook_url": "https://example.com/webhook",
  "webhook_auth_token": "my-secret-token-123",
  "metadata": {
    "description": "Prestação de serviços de segurança, defesa e mediação de conflitos intergalácticos."
  }
}'
Response200
{
  "status": "pending",
  "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
  "name": "Empresa Jedi",
  "date_created": "2026-08-07T15:40:06.997Z",
  "date_updated": "2026-08-07T15:40:06.997Z",
  "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,
  "automatic_withdrawal": true,
  "anticipation_settings": "D1",
  "annual_revenue": 120000,
  "cnae_code": "7490104",
  "legal_nature_code": "4081",
  "company_type": "DEMAIS_PORTES",
  "mother_name": "Padmé Amidala",
  "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",
  "metadata": {
    "description": "Administração pública, diplomacia e relações governamentais."
  }
}'
Response200
{
  "status": "pending",
  "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe",
  "name": "Luke Skywalker",
  "date_created": "2026-08-07T15:40:06.997Z",
  "date_updated": "2026-08-07T15:40:06.998Z",
  "email": "luke@skywalker.com",
  "document": "12345678909"
}