Cadastro

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

Endpoint

POST/v1/merchants

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)
contact	object	—	Informações de contato
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 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

Request

curl -X POST https://yby-dev.positivolabs.com.br/v1/merchants \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
        "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": [
          {
            "bankId": "d1abc1234abc12345680",
            "accountType": "checking",
            "routingNumber": "0001",
            "accountNumber": "12345678-9"
          }
        ],
        "contactPerson": [
          {
            "name": "João Silva",
            "taxId": "12345678900",
            "email": "joao@coffeeshop.com",
            "phone": "+5511988888888",
            "position": "Gerente"
          }
        ]
    }'

Resposta

{
  "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",
  "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 (site, email, phone)
address	object	Endereço comercial (ver Objeto Address)
bankAccounts	array	Contas bancárias associadas
contactPerson	array	Pessoas de contato
createdAt	string	Timestamp de criação (ISO 8601)
updatedAt	string	Timestamp da última atualização (ISO 8601)

Próximos Passos

• Atualizar lojista
• Consultar lojista
• Listar lojistas
• Configurar integrações com adquirentes
• Tratamento de Erros