Skip to main content
POST
/
v1
/
merchants
Create new merchant
curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "full_name": "Merchant Store Ltda.",
  "name": "Merchant Store",
  "document_number": "16525269000121",
  "document_type": "CNPJ",
  "document_tax_type": "PJ",
  "mcc": "5912",
  "contact": {
    "first_name": "Store",
    "last_name": "Manager",
    "phone": "+551188888888",
    "email": "[email protected]",
    "mother_name": "Manager Mother",
    "birth_date": "20-05-1985",
    "document_number": "81146431023",
    "politically_exposed": false,
    "address": {
      "street": "Merchant Street",
      "street_number": "789",
      "neighborhood": "Business District",
      "zipcode": "11223344",
      "country": "076",
      "state": "SP",
      "city": "São Paulo"
    }
  },
  "address": {
    "street": "Store Address",
    "street_number": "456",
    "neighborhood": "Commercial Area",
    "zipcode": "55667788",
    "country": "076",
    "state": "RJ",
    "city": "Rio de Janeiro"
  },
  "transfer_configurations": {
    "automatic_transfer_enabled": true,
    "transfer_frequency": "WEEKLY",
    "rail": "PIX",
    "utc_hour_of_day": 12,
    "day_of_week": 1,
    "day_of_month": 1,
    "min_balance": 1000
  },
  "website_url": "https://merchantstore.com",
  "bank_account": {
    "branch_number": "1234",
    "account_number": "12345-6",
    "account_type": "CHECKING",
    "account_holder_name": "Merchant Store Ltda.",
    "account_holder_document_number": "16525269000121",
    "ispb": "00000000"
  }
}
'
{
  "id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "name": "Example Company",
  "full_name": "Example Company LTDA",
  "document_number": "16525269000121",
  "document_type": "CNPJ",
  "contact": {
    "first_name": "John",
    "last_name": "Silva",
    "phone": "+551199999999",
    "email": "[email protected]",
    "mother_name": "Maria Silva",
    "birth_date": "15-08-1990",
    "document_number": "81146431023",
    "politically_exposed": false,
    "address": {
      "street": "Contact Street",
      "street_number": "456",
      "complement": "Apt 201",
      "neighborhood": "Contact Neighborhood",
      "zipcode": "87654321",
      "country": "076",
      "state": "RJ",
      "city": "Rio de Janeiro"
    }
  },
  "status": "ACTIVE",
  "address": {
    "street": "Example Street",
    "street_number": "123",
    "complement": "Suite 101",
    "neighborhood": "Downtown",
    "zipcode": "12345678",
    "country": "076",
    "state": "SP",
    "city": "São Paulo"
  },
  "transfer_configurations": {
    "automatic_transfer_enabled": true,
    "transfer_frequency": "DAILY",
    "rail": "PIX",
    "utc_hour_of_day": 12,
    "day_of_week": 1,
    "day_of_month": 1,
    "min_balance": 1000
  },
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "document_tax_type": "PJ",
  "company_logo_url": "https://example.com/logo.png",
  "website_url": "https://example.com",
  "webhook_enabled": false
}

Authorizations

​
x-api-key
string
header
required

Company API key for authentication

Body

application/json

Schema for creating a new company or merchant

​
full_name
string
required

Company full name (required)

Example:

"Example Company Ltda."

​
document_number
string
required

Company document number (11 digits for CPF, 14 digits for CNPJ) - digits only

Example:

"16525269000121"

​
document_type
enum<string>
required

Document type (case insensitive, will be converted to uppercase)

Available options:
CPF,
CNPJ
Example:

"CNPJ"

​
document_tax_type
enum<string>
required

Document tax type (required for all companies):

  • PF: Pessoa Física (Individual) - for CPF companies only
  • PJ: Pessoa Jurídica (Legal Entity) - for CNPJ companies
  • MEI: Microempreendedor Individual - for CNPJ companies
  • ME: Microempresa (Micro Enterprise) - for CNPJ companies

Validation Rules:

  • For CPF companies: must be 'PF'
  • For CNPJ companies: must be one of 'PJ', 'MEI', or 'ME'
Available options:
PJ,
MEI,
ME,
PF
Example:

"PJ"

​
mcc
string
required

Merchant Category Code (required)

Example:

"5912"

​
contact
object
required
​
address
object
required
​
transfer_configurations
object
required
​
name
string

Company short name (optional)

Example:

"Example Co"

​
company_logo_url
string<uri>

Company logo URL (optional)

Example:

"https://example.com/logo.png"

​
website_url
string<uri>

Company website URL (optional)

Example:

"https://example.com"

​
fee_policy_id
string

Fee policy ID (optional), will be inherited from organization for merchants

Example:

"507f1f77bcf86cd799439012"

​
metadata
object

Additional metadata (optional JSON object)

Example:
{ "custom_field": "value" }
​
bank_account
object

Bank account information, if sent a bank account will be created for the company

Response

Merchant created successfully

Transformed company data returned by the API

​
id
string
required
Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

​
name
string
required
Example:

"Example Company"

​
full_name
string
required
Example:

"Example Company LTDA"

​
document_number
string
required
Example:

"16525269000121"

​
document_type
enum<string>
required
Available options:
CNPJ,
CPF
Example:

"CNPJ"

​
contact
object
required
​
status
enum<string>
required
Available options:
PENDING_ACTIVATION,
ACTIVE,
INACTIVE,
BLOCKED
Example:

"ACTIVE"

​
address
object
required
​
transfer_configurations
object
required
​
created_at
string<date-time>
required
Example:

"2023-01-01T00:00:00Z"

​
updated_at
string<date-time>
required
Example:

"2023-01-01T00:00:00Z"

​
document_tax_type
enum<string>

Document tax type:

  • PF: Pessoa Física (Individual) - for CPF companies
  • PJ: Pessoa Jurídica (Legal Entity) - for CNPJ companies
  • MEI: Microempreendedor Individual - for CNPJ companies
  • ME: Microempresa (Micro Enterprise) - for CNPJ companies
Available options:
PJ,
MEI,
ME,
PF
Example:

"PJ"

​
company_logo_url
string
Example:

"https://example.com/logo.png"

​
website_url
string
Example:

"https://example.com"

​
webhook_enabled
boolean

Whether webhooks are enabled for this company

Example:

false