Cadastro

Aprenda como criar e integrar um novo comerciante usando a API.

Endpoint

POST/v1/merchants

Request

{
  "dbaName": "Coffee Shop LTDA",
  "corporateName": "Coffee Shop Comércio LTDA",
  "taxId": "12345678000190",
  "merchantCategoryCode": "5347",
  "contact": {
    "site": "http://coffeeshop.com",
    "email": "contact@coffeeshop.com",
    "phone": "+5511999999999"
  },
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Sala 1",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01234567",
    "country": "BR"
  },
  "bankAccounts": [
    {
      "accountType": "checking",
      "routingNumber": "0001",
      "accountNumber": "12345678-9"
    }
  ],
  "contactPerson": [
    {
      "name": "João Silva",
      "taxId": "12345678900",
      "email": "joao@coffeeshop.com",
      "phone": "+5511988888888",
      "position": "Gerente"
    }
  ]
}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
dbaName	string	✓	Nome comercial do comerciante
taxId	string	✓	CNPJ (14 dígitos) ou CPF (11 dígitos)
corporateName	string	✓	Razão social da empresa
merchantCategoryCode	string	✓	Código de categoria do comerciante (MCC, ex.: 5347)
address	object	✓	Endereço comercial
economicActivityCode	string	—	Código de atividade econômica (ex.: 4712100); opcional, não incluído no exemplo acima
contact	object	—	Informações de contato (ver Objeto Contact)
bankAccounts	array	—	Conta(s) bancária(s) do comerciante
contactPerson	array	—	Pessoa(s) de contato do comerciante

Objeto Address

Campo	Tipo	Obrigatório	Descrição
postalCode	string	✓	CEP (8 dígitos, sem hífen)
state	string	✓	Código do estado (2 letras)
city	string	✓	Cidade
neighborhood	string	✓	Bairro / distrito
street	string	✓	Nome da rua
number	string	✓	Número da rua
country	string	—	Código do país (ISO 3166-1 alpha-2, ex.: BR)
complement	string	—	Informação adicional (apartamento, sala, etc.)

Objeto Contact

Campo	Tipo	Obrigatório	Descrição
site	string	—	Website do comerciante
email	string	—	E-mail de contato
phone	string	—	Telefone de contato (formato E.164)

Objeto Bank Account

Campo	Tipo	Obrigatório	Descrição
accountType	string	✓	Tipo de conta (checking, savings)
routingNumber	string	✓	Número da agência
accountNumber	string	✓	Número da conta

Objeto Contact Person

Campo	Tipo	Obrigatório	Descrição
name	string	—	Nome completo
taxId	string	—	CPF
email	string	—	Email
phone	string	—	Número de telefone
position	string	—	Cargo / posição

Response

{
  "id": "d6uo5nc42nrc73gv867g",
  "createdAt": "2026-03-20T10:00:00Z",
  "updatedAt": "2026-03-20T10:00:00Z",
  "type": "merchant",
  "dbaName": "Coffee Shop LTDA",
  "corporateName": "Coffee Shop Comércio LTDA",
  "taxId": "12345678000190",
  "parentId": "d59gpddc93gc73jvje0g",
  "merchantCategoryCode": "5347",
  "economicActivityCode": "4712100",
  "enabled": true,
  "address": {
    "id": "d6uo5nc42nrc73gv8680",
    "postalCode": "01234567",
    "state": "SP",
    "city": "São Paulo",
    "neighborhood": "Centro",
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Sala 1",
    "country": "BR"
  },
  "contact": {
    "id": "d6uo5nc42nrc73gv8681",
    "site": "http://coffeeshop.com",
    "email": "contact@coffeeshop.com",
    "phone": "+5511999999999"
  },
  "bankAccounts": [
    {
      "id": "d6uo5nc42nrc73gv8682",
      "accountType": "checking",
      "routingNumber": "0001",
      "accountNumber": "12345678-9"
    }
  ],
  "contactPerson": [
    {
      "id": "d6uo5nc42nrc73gv8683",
      "name": "João Silva",
      "taxId": "12345678900",
      "email": "joao@coffeeshop.com",
      "phone": "+5511988888888",
      "position": "Gerente"
    }
  ]
}

Campos da Resposta

Campo	Tipo	Descrição
id	string	Identificador único do comerciante (XID, 20 caracteres)
type	string	Tipo de organização — sempre merchant
dbaName	string	Nome comercial / nome fantasia
corporateName	string	Razão social
taxId	string	CNPJ (14 dígitos) ou CPF (11 dígitos)
parentId	string	ID da organização pai (subadquirente)
merchantCategoryCode	string	Código de categoria do comerciante (MCC)
economicActivityCode	string	Código de atividade econômica
enabled	boolean	Se o comerciante está ativo
contact	object	Informações de contato (ver Objeto Contact)
address	object	Endereço comercial (ver Objeto Address)
bankAccounts	array	Contas bancárias associadas (ver Objeto Bank Account)
contactPerson	array	Pessoas de contato (ver Objeto Contact Person)
createdAt	string	Timestamp de criação (ISO 8601)
updatedAt	string	Timestamp da última atualização (ISO 8601)

Na resposta, cada objeto aninhado (address, contact e os itens de bankAccounts e contactPerson) também traz um campo id (XID de 20 caracteres) atribuído pela plataforma.