Merchants — Documentação Funcional

Documentação gerada com base no Swagger merchants.yaml (versão 1.0.0).

1. Visão Geral

O serviço de Merchants é responsável por cadastrar, consultar, atualizar e qualificar os estabelecimentos comerciais que desejam aceitar pagamentos pela plataforma Getnet.

Em linguagem de negócio: quando uma pessoa física (autônomo, profissional liberal), um MEI ou uma empresa (CNPJ) quer começar a receber pagamentos com cartão, link de pagamento, maquininha ou e-commerce pela Getnet, ela precisa ser credenciada. Esse processo de credenciamento — do primeiro cadastro até a aprovação final — é exatamente o que este serviço gerencia.

O serviço resolve os seguintes problemas:

Como cadastrar um novo cliente de adquirência? — Seja pessoa física ou jurídica, o serviço oferece um fluxo guiado de preenchimento de dados, podendo ser feito em uma única etapa ou em múltiplas etapas progressivas.
Como saber se um CPF ou CNPJ já é cliente da Getnet? — Uma consulta rápida responde se o documento já possui um Estabelecimento Comercial (EC) credenciado.
Como manter os dados cadastrais atualizados? — O serviço permite atualizar qualquer informação do cadastro a qualquer momento.
Como validar se o cliente está apto a operar? — O processo de qualificação (análise de risco e compliance) verifica se o estabelecimento pode de fato realizar negócios com a Getnet.

2. Contexto e Casos de Uso

Quando utilizar este serviço

Use este serviço sempre que precisar:

Iniciar o credenciamento de um novo estabelecimento comercial na Getnet.
Consultar dados cadastrais de um estabelecimento já existente.
Atualizar informações cadastrais (endereço, renda, representante legal, etc.).
Verificar previamente se um CPF ou CNPJ já possui vínculo com a Getnet.
Acionar a análise de risco e compliance de um estabelecimento antes de ativá-lo.

Cenários reais de negócio

Cenário 1 — Autônomo querendo aceitar cartão

João é eletricista autônomo e quer uma maquininha da Getnet. O canal coleta seu CPF, nome, data de nascimento, celular, e-mail e nome da mãe. Com esses dados, cria o cadastro de João. Em seguida, complementa os dados de renda, endereço e horário de funcionamento. Por fim, aciona a qualificação para saber se João pode operar.

Cenário 2 — Empresa abrindo credenciamento (PJ)

Uma padaria com CNPJ quer aceitar pagamentos digitais. O canal informa o CNPJ e os dados do representante legal (CPF, nome, celular e e-mail). A plataforma já busca automaticamente os dados da empresa na Receita Federal (razão social, sócios, endereço). O canal complementa com nome fantasia, faturamento anual e endereço comercial, e depois aciona a qualificação.

Cenário 3 — Verificação de duplicidade antes do cadastro

Antes de iniciar o credenciamento, o canal verifica se o CPF ou CNPJ já possui um EC credenciado na Getnet. Se sim, evita a duplicidade. Se não, prossegue com o cadastro normalmente.

Cenário 4 — Atualização de dados cadastrais

Um merchant já credenciado muda de endereço. O canal busca os dados atuais do merchant, altera apenas o campo de endereço no retorno e reenvia o payload completo para atualização.

Cenário 5 — Requalificação após reprovação

Um merchant foi reprovado na qualificação por dados incorretos. Após corrigir as informações via atualização, o canal aciona novamente a qualificação para uma nova análise.

3. Pré-requisitos

Autenticação

Todos os endpoints desta API exigem um token de acesso válido. Esse token deve ser obtido previamente no serviço de autenticação da Getnet:

Como obter: POST /token (domínio Authentication)
Como usar: enviar no header HTTP Authorization diretamente, sem o prefixo Bearer:

text

Authorization: {access_token}

text

Authorization: {access_token}

O token possui prazo de validade. Renove-o antes de iniciar novas requisições quando necessário.

Ambientes disponíveis

Ambiente	URL base
Homologação (testes)	`https://api-homologacao.getnet.com.br:443/v1`
Produção	`https://api-backoffice.getnet.com.br:443/v1`

Dependências de outros serviços

Alguns dados exigidos na jornada de credenciamento dependem de consultas a outros domínios da plataforma. Estas chamadas não são obrigatórias, mas são fortemente recomendadas para evitar erros na qualificação:

Serviço	Quando usar
`GET /domains/acquirer-merchant-categories`	Para obter os códigos de categoria de atividade econômica disponíveis (PF e PJ). Filtre por `?natural_person` para listar apenas as categorias de pessoa física.
`GET /domains/zipcode/{postal_code}`	Para validar o CEP e obter automaticamente os dados do endereço (rua, bairro, cidade, estado). CEP inválido causa reprovação na qualificação.
`GET /domains/countries`	Para obter os códigos de país válidos, usados nos campos `nationality` e `country_of_birth`.

Permissões e perfis

O canal integrado deve estar devidamente habilitado na plataforma Getnet para operar o domínio de Merchants.
As credenciais utilizadas para obter o token devem ter permissão de leitura e escrita sobre os recursos deste domínio.

4. Fluxo Principal

O credenciamento de um merchant segue um fluxo em etapas, da verificação inicial até a aprovação final. Os endpoints se relacionam da seguinte forma:

text

┌─────────────────────────────────────────────────────────────────────┐
│                    FLUXO DE CREDENCIAMENTO                          │
└─────────────────────────────────────────────────────────────────────┘

  ETAPA 0 — Verificação prévia (opcional, mas recomendada)
  ─────────────────────────────────────────────────────────
  600;">GET /establishment-contracts-basic/legal-document-number/{cpf_cnpj}/ec-accredited
       │
       ├── accredited: true  ──► Documento já possui EC. Não prosseguir com cadastro.
       │
       └── accredited: false ──► Pode cadastrar. Seguir para ETAPA 1.


  ETAPA 1 — Criação do merchant (dados mínimos)
  ──────────────────────────────────────────────
  600;">POST /merchants
       │
       Enviar: CPF/CNPJ + dados pessoais básicos + opt-ins (LGPD + termos)
       │
       Retorna: merchant_id + sub_status_steps (etapas pendentes)
       │
       └──► Guardar o merchant_id para usar nas etapas seguintes.


  ETAPA 2 — Complemento de dados (quando necessário)
  ────────────────────────────────────────────────────
  600;">GET /merchants/{merchant_id}          <- Obter estado atual completo
       │
       Alterar somente os campos necessários no payload retornado
       │
  600;">PUT /merchants/{merchant_id}          <- Reenviar payload completo atualizado
       │
       Enviar: renda, patrimônio, endereços, horário de funcionamento, etc.
       │
       ATENCAO: NUNCA enviar payload parcial — o 600;">PUT substitui todos os dados.


  ETAPA 3 — Qualificação (análise de risco e compliance)
  ───────────────────────────────────────────────────────
  600;">POST /merchants/{merchant_id}/qualification
       │
       Retorna 200 (síncrono) ou 202 (assíncrono)
       │
       ├── 200: resultado disponível imediatamente
       │         └── Verificar: report.recommended.status
       │
       └── 202: processamento em andamento
                 └── Consultar resultado via:
                     600;">GET /merchants/{merchant_id}/qualification


  ETAPA 4 — Resultado da qualificação
  ────────────────────────────────────
       report.recommended.status
       │
       ├── "approved" ──► Merchant aprovado. Prosseguir com as próximas
       │                   etapas do credenciamento (ofertas, contratos).
       │
       └── "reproved" ──► Merchant reprovado. Consultar motivo em:
                           report.details[*].detail_description

text

┌─────────────────────────────────────────────────────────────────────┐
│                    FLUXO DE CREDENCIAMENTO                          │
└─────────────────────────────────────────────────────────────────────┘

  ETAPA 0 — Verificação prévia (opcional, mas recomendada)
  ─────────────────────────────────────────────────────────
  600;">GET /establishment-contracts-basic/legal-document-number/{cpf_cnpj}/ec-accredited
       │
       ├── accredited: true  ──► Documento já possui EC. Não prosseguir com cadastro.
       │
       └── accredited: false ──► Pode cadastrar. Seguir para ETAPA 1.


  ETAPA 1 — Criação do merchant (dados mínimos)
  ──────────────────────────────────────────────
  600;">POST /merchants
       │
       Enviar: CPF/CNPJ + dados pessoais básicos + opt-ins (LGPD + termos)
       │
       Retorna: merchant_id + sub_status_steps (etapas pendentes)
       │
       └──► Guardar o merchant_id para usar nas etapas seguintes.


  ETAPA 2 — Complemento de dados (quando necessário)
  ────────────────────────────────────────────────────
  600;">GET /merchants/{merchant_id}          <- Obter estado atual completo
       │
       Alterar somente os campos necessários no payload retornado
       │
  600;">PUT /merchants/{merchant_id}          <- Reenviar payload completo atualizado
       │
       Enviar: renda, patrimônio, endereços, horário de funcionamento, etc.
       │
       ATENCAO: NUNCA enviar payload parcial — o 600;">PUT substitui todos os dados.


  ETAPA 3 — Qualificação (análise de risco e compliance)
  ───────────────────────────────────────────────────────
  600;">POST /merchants/{merchant_id}/qualification
       │
       Retorna 200 (síncrono) ou 202 (assíncrono)
       │
       ├── 200: resultado disponível imediatamente
       │         └── Verificar: report.recommended.status
       │
       └── 202: processamento em andamento
                 └── Consultar resultado via:
                     600;">GET /merchants/{merchant_id}/qualification


  ETAPA 4 — Resultado da qualificação
  ────────────────────────────────────
       report.recommended.status
       │
       ├── "approved" ──► Merchant aprovado. Prosseguir com as próximas
       │                   etapas do credenciamento (ofertas, contratos).
       │
       └── "reproved" ──► Merchant reprovado. Consultar motivo em:
                           report.details[*].detail_description

Descrição de cada endpoint

Método	Endpoint	O que faz
`GET`	`/establishment-contracts-basic/legal-document-number/{doc}/ec-accredited`	Verifica se o CPF ou CNPJ já possui EC credenciado. Use antes de iniciar um novo cadastro.
`GET`	`/merchants`	Lista merchants por CPF/CNPJ ou código EC, com paginação e filtros de status e tipo.
`POST`	`/merchants`	Cria um novo merchant. Aceita dados mínimos e permite complementação posterior.
`GET`	`/merchants/{merchant_id}`	Retorna todos os dados de um merchant específico. Obrigatório antes de qualquer atualização.
`PUT`	`/merchants/{merchant_id}`	Atualiza os dados do merchant com substituição total. Sempre usar o retorno do GET como base.
`POST`	`/merchants/{merchant_id}/qualification`	Dispara a análise de risco e compliance do merchant.
`GET`	`/merchants/{merchant_id}/qualification`	Consulta o resultado da última qualificação. Útil quando o POST retornou `202`.

Diferenças entre PF e PJ no fluxo

text

PESSOA FÍSICA (PF)                    PESSOA JURÍDICA (PJ)
  ──────────────────                    ────────────────────
  fiscal_type: natural_person           fiscal_type: company

  Dados mínimos no 600;">POST:                Dados mínimos no 600;">POST:
  • CPF                                 • CNPJ
  • Nome completo                       • Telefone da empresa
  • Data de nascimento                  • CPF + dados do representante legal
  • Celular + e-mail                      (nome, nascimento, celular, e-mail)
  • Nome da mãe
  • Nacionalidade + país de nascimento
  • Categoria de atividade (MCC)

  Complementar via 600;">PUT:                 Complementar via 600;">PUT:
  • Renda bruta mensal                  • Nome fantasia
  • Patrimônio líquido                  • Faturamento bruto anual
  • Endereço residencial                • Patrimônio líquido da empresa
  • Endereço comercial                  • Endereço comercial da empresa
  • Horário de funcionamento            • Endereços do representante legal
                                        • Horário de funcionamento

  Etapas extras de onboarding (PJ):
  • SOCIAL_CONTRACT    — envio do contrato social
  • LETTER_OF_ATTORNEY — envio de procuração (quando aplicável)

  Dados preenchidos automaticamente (PJ):
  • Razão social, data de fundação, regime tributário (via CNPJ/Receita Federal)
  • Quadro societário completo (shareholders)

text

PESSOA FÍSICA (PF)                    PESSOA JURÍDICA (PJ)
  ──────────────────                    ────────────────────
  fiscal_type: natural_person           fiscal_type: company

  Dados mínimos no 600;">POST:                Dados mínimos no 600;">POST:
  • CPF                                 • CNPJ
  • Nome completo                       • Telefone da empresa
  • Data de nascimento                  • CPF + dados do representante legal
  • Celular + e-mail                      (nome, nascimento, celular, e-mail)
  • Nome da mãe
  • Nacionalidade + país de nascimento
  • Categoria de atividade (MCC)

  Complementar via 600;">PUT:                 Complementar via 600;">PUT:
  • Renda bruta mensal                  • Nome fantasia
  • Patrimônio líquido                  • Faturamento bruto anual
  • Endereço residencial                • Patrimônio líquido da empresa
  • Endereço comercial                  • Endereço comercial da empresa
  • Horário de funcionamento            • Endereços do representante legal
                                        • Horário de funcionamento

  Etapas extras de onboarding (PJ):
  • SOCIAL_CONTRACT    — envio do contrato social
  • LETTER_OF_ATTORNEY — envio de procuração (quando aplicável)

  Dados preenchidos automaticamente (PJ):
  • Razão social, data de fundação, regime tributário (via CNPJ/Receita Federal)
  • Quadro societário completo (shareholders)

5. Guia de Integração Rápida

Esta seção apresenta o caminho mais comum de uso da API — o happy path — para credenciar um merchant PF e um merchant PJ do início ao fim.

Happy Path — Pessoa Física (PF)

text

PASSO 1        PASSO 2              PASSO 3           PASSO 4
  Verificar  →   Criar merchant   →   Complementar  →   Qualificar
  duplicidade    (600;">POST /merchants)    dados (600;">PUT)        (600;">POST /qualification)

text

PASSO 1        PASSO 2              PASSO 3           PASSO 4
  Verificar  →   Criar merchant   →   Complementar  →   Qualificar
  duplicidade    (600;">POST /merchants)    dados (600;">PUT)        (600;">POST /qualification)

Passo 1 — Verificar se o CPF já é cliente

Antes de cadastrar, consulte se o CPF já possui EC credenciado:

text

GET /establishment-contracts-basic/legal-document-number/24751750011/ec-accredited

text

GET /establishment-contracts-basic/legal-document-number/24751750011/ec-accredited

Retorno esperado (pode prosseguir):

json

{
  "accredited": false
}

json

{
  "accredited": false
}

Se accredited: true, o CPF já possui vínculo. Não crie um novo cadastro.

Passo 2 — Criar o merchant PF (dados mínimos)

Envie os dados essenciais para criar o cadastro. Os dados complementares serão enviados no próximo passo.

Requisição:

text

600;">POST /merchants

text

600;">POST /merchants

json

{
  "acquirer_code": "getnet",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "phone": null,
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "mothers_name": "MARIA DA SILVA",
      "country_of_birth": "BR"
    }
  },
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  }
}

json

{
  "acquirer_code": "getnet",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "phone": null,
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "mothers_name": "MARIA DA SILVA",
      "country_of_birth": "BR"
    }
  },
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  }
}

O que enviar:

fiscal_type: sempre "natural_person" para PF.

acquirer_merchant_category_code: use "2119" (Profissional Autônomo) quando não souber a categoria específica.

opt_ins: obrigatório com lgpd e terms_and_conditions, ambos com accept: true.

Retorno esperado (HTTP 200):

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } },
      { "name": "CELL_PHONE", "situation": { "status": "pending" } },
      { "name": "EMAIL", "situation": { "status": "pending" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f23739a4f90ca92a85686",
    "acquirer_merchant_code": "55317249",
    "situation": { "status": "accepted" }
  },
  "reports": null
}

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } },
      { "name": "CELL_PHONE", "situation": { "status": "pending" } },
      { "name": "EMAIL", "situation": { "status": "pending" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f23739a4f90ca92a85686",
    "acquirer_merchant_code": "55317249",
    "situation": { "status": "accepted" }
  },
  "reports": null
}

O que observar no retorno:

Guarde o merchant_id — ele será necessário em todos os passos seguintes.

O campo sub_status_steps lista as etapas ainda pendentes. DATA_GRID com status: pending indica que dados complementares ainda precisam ser enviados.

TERMS_AND_CONDITIONS e PRIVACY_POLICY já aparecem como finished porque os opt-ins foram enviados no POST.

Passo 3 — Complementar os dados (PUT)

Antes de qualquer atualização, consulte o estado atual do merchant:

text

GET /merchants/6a0f23739a4f90ca92a85686

text

GET /merchants/6a0f23739a4f90ca92a85686

Sobre o retorno obtido, adicione/altere os campos complementares e reenvie o payload completo:

text

PUT /merchants/6a0f23739a4f90ca92a85686

text

PUT /merchants/6a0f23739a4f90ca92a85686

json

{
  "acquirer_code": "getnet",
  "merchant_id": "6a0f23739a4f90ca92a85686",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "country_of_birth": "BR",
      "mothers_name": "MARIA DA SILVA",
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "gross_monthly_income": 500000,
      "net_worth": 2000000,
      "residential_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "commercial_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "working_hours": [
        {
          "start_day": "mon",
          "end_day": "fri",
          "start_time": "08:00:00",
          "end_time": "18:00:00"
        }
      ]
    }
  }
}

json

{
  "acquirer_code": "getnet",
  "merchant_id": "6a0f23739a4f90ca92a85686",
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "natural_person",
      "legal_document_number": "24751750011",
      "name": "JOÃO DA SILVA SANTOS",
      "birth_date": "1985-03-22",
      "cell_phone": "11987654321",
      "email": "joao.santos@email.com",
      "nationality": "BR",
      "country_of_birth": "BR",
      "mothers_name": "MARIA DA SILVA",
      "economic_activity_profile": {
        "acquirer_merchant_category_code": "2119"
      },
      "gross_monthly_income": 500000,
      "net_worth": 2000000,
      "residential_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "commercial_address": {
        "postal_code": "01321001",
        "street": "RUA MARTINIANO DE CARVALHO",
        "number": "611",
        "suite": "AP 64",
        "district": "BELA VISTA",
        "city": "SAO PAULO",
        "state": "SP",
        "country": "BR"
      },
      "working_hours": [
        {
          "start_day": "mon",
          "end_day": "fri",
          "start_time": "08:00:00",
          "end_time": "18:00:00"
        }
      ]
    }
  }
}

Atenção:

O PUT é uma substituição total. Sempre parta do retorno do GET e altere apenas o necessário.

Valores monetários em centavos: 500000 = R$ 5.000,00.

O CEP informado deve existir na base da Getnet. Valide com GET /domains/zipcode/{postal_code} antes de enviar.

commercial_address e residential_address podem ser iguais (comum para autônomos).

Passo 4 — Qualificar o merchant PF

Com os dados completos, acione a análise de risco:

text

POST /merchants/6a0f23739a4f90ca92a85686/qualification

text

POST /merchants/6a0f23739a4f90ca92a85686/qualification

O corpo da requisição pode ser omitido para a qualificação padrão.

Retorno — Merchant aprovado (HTTP 200):

json

{
  "report": {
    "recommended": {
      "status": "approved"
    },
    "details": []
  }
}

json

{
  "report": {
    "recommended": {
      "status": "approved"
    },
    "details": []
  }
}

Retorno — Merchant reprovado (HTTP 200):

json

{
  "report": {
    "recommended": {
      "status": "reproved"
    },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_attribute": "merchant.merchant_legal_data.person.legal_document_number",
        "detail_description": "Prezado Cliente, agradecemos seu contato mas no momento nossos serviços não estão disponíveis para seu negócio.",
        "detail_code": "QR-8003"
      }
    ]
  }
}

json

{
  "report": {
    "recommended": {
      "status": "reproved"
    },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_attribute": "merchant.merchant_legal_data.person.legal_document_number",
        "detail_description": "Prezado Cliente, agradecemos seu contato mas no momento nossos serviços não estão disponíveis para seu negócio.",
        "detail_code": "QR-8003"
      }
    ]
  }
}

approved: merchant habilitado. Prossiga para as próximas etapas (ofertas, contratos).

reproved: leia detail_description em cada item de details para entender o motivo. Quando o motivo não puder ser divulgado, a mensagem será genérica (conforme exemplo acima).

Happy Path — Pessoa Jurídica (PJ)

text

PASSO 1        PASSO 2              PASSO 3           PASSO 4
  Verificar  →   Criar merchant   →   Complementar  →   Qualificar
  duplicidade    (600;">POST /merchants)    dados (600;">PUT)        (600;">POST /qualification)

text

PASSO 1        PASSO 2              PASSO 3           PASSO 4
  Verificar  →   Criar merchant   →   Complementar  →   Qualificar
  duplicidade    (600;">POST /merchants)    dados (600;">PUT)        (600;">POST /qualification)

Passo 1 — Verificar se o CNPJ já é cliente

text

GET /establishment-contracts-basic/legal-document-number/07221119000163/ec-accredited

text

GET /establishment-contracts-basic/legal-document-number/07221119000163/ec-accredited

Retorno esperado (pode prosseguir):

json

{
  "accredited": false
}

json

{
  "accredited": false
}

Passo 2 — Criar o merchant PJ (dados mínimos)

text

600;">POST /merchants

text

600;">POST /merchants

json

{
  "acquirer_code": "getnet",
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  },
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "company",
      "legal_document_number": "07221119000163",
      "phone": "51999999999",
      "annual_gross_income": null,
      "net_worth": null,
      "monthly_card_income": null,
      "legal_representative": {
        "fiscal_type": "natural_person",
        "legal_document_number": "24751750011",
        "name": "JOÃO DA SILVA SANTOS",
        "birth_date": "1985-03-22",
        "cell_phone": "51999999999",
        "email": "joao.santos@empresa.com.br",
        "gross_monthly_income": null,
        "mothers_name": null,
        "nationality": null,
        "net_worth": null
      }
    }
  }
}

json

{
  "acquirer_code": "getnet",
  "additional_information": {
    "shared_data": {
      "opt_ins": [
        { "opt_in_type": "lgpd", "accept": true },
        { "opt_in_type": "terms_and_conditions", "accept": true }
      ]
    }
  },
  "merchant_legal_data": {
    "country": "BR",
    "person": {
      "fiscal_type": "company",
      "legal_document_number": "07221119000163",
      "phone": "51999999999",
      "annual_gross_income": null,
      "net_worth": null,
      "monthly_card_income": null,
      "legal_representative": {
        "fiscal_type": "natural_person",
        "legal_document_number": "24751750011",
        "name": "JOÃO DA SILVA SANTOS",
        "birth_date": "1985-03-22",
        "cell_phone": "51999999999",
        "email": "joao.santos@empresa.com.br",
        "gross_monthly_income": null,
        "mothers_name": null,
        "nationality": null,
        "net_worth": null
      }
    }
  }
}

O que enviar:

fiscal_type da empresa: sempre "company".

fiscal_type do representante legal: sempre "natural_person".

Dados da empresa (razão social, endereço, sócios) são buscados automaticamente via CNPJ na Receita Federal — não é necessário informá-los.

opt_ins é obrigatório já no POST.

Retorno esperado (HTTP 200) — destaques:

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "SOCIAL_CONTRACT", "situation": { "status": "pending" } },
      { "name": "LETTER_OF_ATTORNEY", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f43fd9a4f90ca92a8596d",
    "acquirer_merchant_code": "55317268",
    "merchant_legal_data": {
      "person": {
        "fiscal_type": "company",
        "legal_name": "NOME FANTASIA DA EMPRESA",
        "founding_date": "2014-04-30",
        "tax_regime": "EIRELI",
        "federal_registration_status": "active"
      }
    }
  }
}

json

{
  "situation": {
    "status": "accepted",
    "sub_status_steps": [
      { "name": "DATA_GRID", "situation": { "status": "pending" } },
      { "name": "SOCIAL_CONTRACT", "situation": { "status": "pending" } },
      { "name": "LETTER_OF_ATTORNEY", "situation": { "status": "pending" } },
      { "name": "TERMS_AND_CONDITIONS", "situation": { "status": "finished" } },
      { "name": "PRIVACY_POLICY", "situation": { "status": "finished" } }
    ]
  },
  "merchant": {
    "merchant_id": "6a0f43fd9a4f90ca92a8596d",
    "acquirer_merchant_code": "55317268",
    "merchant_legal_data": {
      "person": {
        "fiscal_type": "company",
        "legal_name": "NOME FANTASIA DA EMPRESA",
        "founding_date": "2014-04-30",
        "tax_regime": "EIRELI",
        "federal_registration_status": "active"
      }
    }
  }
}

O que observar:

merchant_id retornado deve ser guardado para os próximos passos.

A plataforma já preencheu automaticamente: legal_name, founding_date, tax_regime, federal_registration_status e o quadro societário (shareholders).

SOCIAL_CONTRACT e LETTER_OF_ATTORNEY são etapas exclusivas de PJ.

Passo 3 — Complementar os dados PJ (PUT)

Consulte o estado atual:

text

GET /merchants/6a0f43fd9a4f90ca92a8596d

text

GET /merchants/6a0f43fd9a4f90ca92a8596d

Sobre o retorno do GET, adicione os dados complementares e reenvie:

text

PUT /merchants/6a0f43fd9a4f90ca92a8596d

text

PUT /merchants/6a0f43fd9a4f90ca92a8596d

Principais campos a complementar para PJ:

Campo	Exemplo
`trade_name`	`"PADARIA BOA HORA"`
`annual_gross_income`	`25000000` (= R$ 250.000,00)
`net_worth`	`5000000` (= R$ 50.000,00)
`business_address`	Endereço comercial da empresa (CEP válido)
`working_hours`	Horário de funcionamento
`legal_representative.country_of_birth`	`"BR"`
`legal_representative.nationality`	`"BR"`
`legal_representative.gross_monthly_income`	`1500000` (= R$ 15.000,00)
`legal_representative.net_worth`	`3000000` (= R$ 30.000,00)
`legal_representative.residential_address`	Endereço residencial do representante
`legal_representative.commercial_address`	Endereço comercial do representante

Atenção para o quadro societário (shareholders): O array shareholders é preenchido automaticamente pela plataforma. Reenvie-o exatamente como retornado pelo GET — não omita, altere ou reordene os sócios.

Passo 4 — Qualificar o merchant PJ

text

POST /merchants/6a0f43fd9a4f90ca92a8596d/qualification

text

POST /merchants/6a0f43fd9a4f90ca92a8596d/qualification

O retorno e a interpretação são os mesmos da PF:

report.recommended.status: "approved" → merchant habilitado.
report.recommended.status: "reproved" → consulte report.details[*].detail_description.

Qualificação assíncrona: se o retorno for HTTP 202 (em vez de 200), o processamento ainda está em andamento. Consulte o resultado com:

text
GET /merchants/6a0f43fd9a4f90ca92a8596d/qualification
text
GET /merchants/6a0f43fd9a4f90ca92a8596d/qualification

6. Regras de Negócio

Regras gerais

Parâmetro obrigatório na listagem

Ao consultar a lista de merchants (GET /merchants), é obrigatório informar ao menos um dos parâmetros abaixo. A ausência de ambos retorna erro 400:

legal_document_number — CPF (11 dígitos) ou CNPJ (14 dígitos), somente dígitos.
acquirer_merchant_code — Código EC na Getnet.

Paginação da listagem

Parâmetro	Padrão	Mínimo	Máximo
`page`	`1`	`1`	—
`limit`	`25`	`1`	`200`

Regras de criação — POST /merchants

Opt-ins obrigatórios

O campo additional_information.shared_data.opt_ins é obrigatório no POST /merchants e deve conter os dois tipos abaixo, ambos com accept: true:

`opt_in_type`	Descrição
`lgpd`	Consentimento para tratamento de dados pessoais conforme a LGPD.
`terms_and_conditions`	Aceite dos termos e condições de uso da plataforma.

Campos obrigatórios no POST — Pessoa Física (PF)

Campo	Formato / Restrição
`acquirer_code`	Fixo: `"getnet"`
`fiscal_type`	Fixo: `"natural_person"`
`legal_document_number`	CPF — exatamente 11 dígitos numéricos, sem máscara
`name`	Nome completo
`birth_date`	Formato `YYYY-MM-DD`
`cell_phone`	10 a 11 dígitos (DDD + número), somente dígitos
`email`	Formato de e-mail válido
`nationality`	Código ISO 3166-1 alpha-2 (ex.: `"BR"`). Deve existir em `GET /domains/countries`
`country_of_birth`	Código ISO 3166-1 alpha-2 (ex.: `"BR"`). Deve existir em `GET /domains/countries`
`mothers_name`	Nome completo da mãe
`acquirer_merchant_category_code`	Código válido obtido via `GET /domains/acquirer-merchant-categories`. Usar `"2119"` como padrão para PF

Campos obrigatórios no POST — Pessoa Jurídica (PJ)

Campo	Formato / Restrição
`acquirer_code`	Fixo: `"getnet"`
`fiscal_type`	Fixo: `"company"`
`legal_document_number`	CNPJ — exatamente 14 dígitos numéricos, sem máscara
`phone`	10 a 11 dígitos (DDD + número), somente dígitos
`legal_representative.fiscal_type`	Fixo: `"natural_person"`
`legal_representative.legal_document_number`	CPF — exatamente 11 dígitos numéricos
`legal_representative.name`	Nome completo do representante legal
`legal_representative.birth_date`	Formato `YYYY-MM-DD`
`legal_representative.cell_phone`	10 a 11 dígitos, somente dígitos
`legal_representative.email`	Formato de e-mail válido

Regras de atualização — PUT /merchants/{merchant_id}

Substituição total (full replace)

O PUT /merchants/{merchant_id} substitui todos os dados do merchant. Campos omitidos serão removidos do cadastro. O fluxo obrigatório é:

text

600;">GET  /merchants/{merchant_id}   →  Obter estado atual completo
Modificar apenas o(s) campo(s) desejado(s) no retorno obtido
600;">PUT  /merchants/{merchant_id}   →  Reenviar o payload completo

text

600;">GET  /merchants/{merchant_id}   →  Obter estado atual completo
Modificar apenas o(s) campo(s) desejado(s) no retorno obtido
600;">PUT  /merchants/{merchant_id}   →  Reenviar o payload completo

Nunca envie um payload parcial no PUT.

Quadro societário (PJ)

O array shareholders é preenchido automaticamente pela plataforma via Receita Federal. Ao fazer o PUT, reenvie-o exatamente como retornado pelo GET — sem omitir, alterar ou reordenar sócios.

Regras de endereço

Aplicam-se a todos os campos de endereço: commercial_address, residential_address (PF) e business_address (PJ), incluindo os endereços do representante legal.

Regra	Detalhe
CEP obrigatório	Campo `postal_code` é obrigatório. Formato: 8 dígitos numéricos, sem hífen (ex.: `"01321001"`).
CEP deve existir na base da Getnet	CEP inexistente causa reprovação do merchant na qualificação. Valide previamente com `GET /domains/zipcode/{postal_code}` (recomendado).
`number` ou `suite`	`number` é obrigatório quando o imóvel possui número. Quando não há número, o campo `suite` (complemento) torna-se obrigatório.
CEP de abrangência municipal	Quando `GET /domains/zipcode/{postal_code}` não retornar `street` e `district`, esses dados devem ser coletados do merchant e informados manualmente.
Endereços iguais permitidos	`commercial_address` e `residential_address` podem conter os mesmos dados (comum para autônomos).

Regras de valores monetários

Todos os campos de valor monetário são expressos em centavos (inteiros):

Campo	Exemplo	Equivalente
`gross_monthly_income`	`1500000`	R$ 15.000,00
`net_worth`	`5000000`	R$ 50.000,00
`annual_gross_income`	`25000000`	R$ 250.000,00
`monthly_card_income`	`3000000`	R$ 30.000,00

Regras de qualificação

Regra	Detalhe
Campo principal do resultado	Sempre verifique `report.recommended.status`. Os valores possíveis são `"approved"` (apto) e `"reproved"` (reprovado).
Reprovação com motivo genérico	Quando o motivo da reprovação não puder ser divulgado por políticas internas da Getnet, `detail_description` retornará uma mensagem genérica. Isso é esperado e não indica falha na integração.
Qualificação assíncrona	O retorno `HTTP 202` indica que o processamento ainda está em andamento. Consulte o resultado via `GET /merchants/{merchant_id}/qualification`.
Modo simulação	É possível executar a qualificação em modo de simulação enviando `{ "validation": true }` no body. O estado do merchant não é alterado nesse modo.

Status do ciclo de vida do merchant

Status	Significado
`accepted`	Cadastro recebido. Merchant criado, mas dados complementares podem estar pendentes.
`pending_qualification`	Aguardando acionamento da qualificação (KYC).
`under_analysis`	Em análise pelo time de risco e compliance da Getnet.
`approved`	Aprovado e pronto para receber ofertas e contratos.
`active`	Ativo e transacionando.
`rejected`	Reprovado na qualificação. Não poderá operar.
`blocked`	Bloqueado temporariamente.
`cancelled`	Cancelado ou descredenciado.

Etapas do onboarding (sub_status_steps)

Etapa	Quem tem	Descrição
`DATA_GRID`	PF e PJ	Dados complementares ainda pendentes de preenchimento (renda, endereço, horário, etc.).
`SELFIE`	PF e PJ	Envio de selfie para validação biométrica.
`IDENTIFICATION_DOCUMENT`	PF e PJ	Envio de documento de identidade.
`TERMS_AND_CONDITIONS`	PF e PJ	Aceite dos termos de uso (concluído automaticamente quando opt-in é enviado no POST).
`PRIVACY_POLICY`	PF e PJ	Aceite da política de privacidade (concluído automaticamente).
`ORDER_SUMMARY`	PF e PJ	Confirmação do resumo do pedido.
`CELL_PHONE`	PF e PJ	Validação do número de celular por código OTP.
`EMAIL`	PF e PJ	Validação do e-mail por código OTP.
`SOCIAL_CONTRACT`	PJ apenas	Envio do contrato social da empresa.
`LETTER_OF_ATTORNEY`	PJ apenas	Envio de procuração quando o representante legal não é sócio.

7. Tratamento de Erros

Estrutura padrão de erro

Todos os erros seguem a estrutura abaixo:

json

{
  "status_code": 400,
  "message": "Requisição inválida.",
  "error_code": "MERCHANT_DOCUMENT_INVALID",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

json

{
  "status_code": 400,
  "message": "Requisição inválida.",
  "error_code": "MERCHANT_DOCUMENT_INVALID",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

Campo	Descrição
`status_code`	Código HTTP do erro.
`message`	Mensagem geral descrevendo o problema.
`error_code`	Código interno de negócio (quando disponível). Útil para tratamento programático.
`details`	Lista de erros campo a campo (presente em erros `400` e `422`).

Códigos de erro por endpoint

Código HTTP	Nome	Endpoints onde ocorre	O que significa	O que fazer
`400`	Bad Request	Todos	A requisição está malformada ou faltam parâmetros obrigatórios. Verifique o array `details` para identificar campo a campo o problema.	Corrija os campos indicados em `details` e reenvie a requisição. No `GET /merchants`, certifique-se de informar `legal_document_number` ou `acquirer_merchant_code`.
`401`	Unauthorized	Todos	O token de acesso está ausente, inválido ou expirado.	Obtenha um novo token via `POST /token` e reenvie a requisição com o header `Authorization` correto (sem prefixo `Bearer`).
`403`	Forbidden	Todos	O token é válido, mas o canal não tem permissão para acessar o recurso solicitado.	Verifique se as credenciais utilizadas possuem permissão para o domínio Merchants. Contate o suporte se necessário.
`404`	Not Found	`GET /merchants/{merchant_id}`, `PUT /merchants/{merchant_id}`, `GET /qualification`, `GET /ec-accredited`	O recurso solicitado não foi encontrado. O `merchant_id` pode estar incorreto ou o merchant pode não existir no ambiente consultado.	Verifique se o `merchant_id` foi obtido do retorno do `POST /merchants` e se você está consultando o ambiente correto (homologação vs. produção).
`409`	Conflict	`POST /merchants`	Já existe um merchant cadastrado com o documento (CPF ou CNPJ) informado.	Utilize `GET /merchants?legal_document_number={doc}` para localizar o cadastro existente, ou verifique previamente com `GET /ec-accredited` antes de criar.
`422`	Unprocessable Entity	`POST /merchants`, `PUT /merchants/{merchant_id}`, `GET /ec-accredited`, `POST /qualification`	A requisição é sintaticamente válida, mas viola regras de negócio. Exemplos: CEP inválido, código de categoria inexistente, CPF/CNPJ com formato incorreto.	Verifique o array `details` para identificar qual campo gerou a violação. Corrija o valor e reenvie.
`500`	Internal Server Error	Todos	Erro interno inesperado na plataforma. Não relacionado ao payload enviado.	Aguarde alguns instantes e tente novamente. Se o erro persistir, abra um chamado no suporte Getnet informando o `request_id` da requisição.

Cenários de erro mais comuns

Criação com documento já existente (409)

json

{
  "status_code": 409,
  "message": "Merchant já existente para o documento informado.",
  "error_code": "MERCHANT_ALREADY_EXISTS"
}

json

{
  "status_code": 409,
  "message": "Merchant já existente para o documento informado.",
  "error_code": "MERCHANT_ALREADY_EXISTS"
}

O que fazer: consulte o merchant existente com GET /merchants?legal_document_number={doc} para obter o merchant_id e continuar a jornada a partir do cadastro já criado.

Campo obrigatório ausente (400)

json

{
  "status_code": 400,
  "message": "Requisição inválida.",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

json

{
  "status_code": 400,
  "message": "Requisição inválida.",
  "details": [
    {
      "item": "legal_document_number",
      "description": "Documento inválido."
    }
  ]
}

O que fazer: corrija o campo indicado em details.item e reenvie. Verifique formato (dígitos, tamanho) e se o valor está no padrão esperado.

Merchant reprovado na qualificação (200 com status reproved)

json

{
  "report": {
    "recommended": { "status": "reproved" },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_code": "QR-8003",
        "detail_description": "Prezado Cliente, agradecemos seu contato mas no momento nossos serviços não estão disponíveis para seu negócio."
      }
    ]
  }
}

json

{
  "report": {
    "recommended": { "status": "reproved" },
    "details": [
      {
        "detail_type": "blacklist",
        "detail_code": "QR-8003",
        "detail_description": "Prezado Cliente, agradecemos seu contato mas no momento nossos serviços não estão disponíveis para seu negócio."
      }
    ]
  }
}

O que fazer: a reprovação retorna sempre HTTP 200 — não é um erro de integração. Verifique detail_description para entender o motivo. Quando a mensagem for genérica (como no exemplo), o motivo não pode ser divulgado por políticas internas da Getnet. O merchant não poderá operar.

Token expirado (401)

json

{
  "status_code": 401,
  "message": "Token de acesso ausente, inválido ou expirado."
}

json

{
  "status_code": 401,
  "message": "Token de acesso ausente, inválido ou expirado."
}

O que fazer: obtenha um novo token via POST /token (domínio Authentication) e reenvie a requisição com o novo valor no header Authorization.

8. Glossário

Termo	Definição
Merchant	Estabelecimento comercial credenciado — cliente de adquirência da Getnet. Pode ser Pessoa Física (PF), MEI ou Pessoa Jurídica (PJ).
EC (Estabelecimento Comercial)	Código único atribuído pelo adquirente (Getnet) ao merchant credenciado. Também chamado de `acquirer_merchant_code`.
Credenciamento	Processo pelo qual um cliente (PF ou PJ) é cadastrado e habilitado a aceitar pagamentos pela Getnet.
Onboarding	Jornada completa de entrada do merchant na plataforma, do primeiro cadastro até a aprovação final.
Qualificação (KYC)	Processo de análise de risco e compliance que verifica se o merchant está apto a realizar negócios com a Getnet. KYC = Know Your Customer (Conheça Seu Cliente).
Pessoa Física (PF)	Merchant cadastrado com CPF. Inclui autônomos, profissionais liberais e pessoas físicas em geral.
Pessoa Jurídica (PJ)	Merchant cadastrado com CNPJ. Inclui empresas de qualquer porte e regime tributário.
MEI	Microempreendedor Individual — categoria especial de PJ com CNPJ e características próprias de credenciamento.
Representante Legal	Pessoa física (CPF) autorizada a agir em nome da empresa (PJ) perante a Getnet. Pode ser sócio, diretor ou procurador.
Beneficiário Final	Pessoa física que, em última instância, controla ou se beneficia da empresa. Identificado automaticamente a partir do quadro societário consultado na Receita Federal.
Quadro Societário (Shareholders)	Lista de sócios e beneficiários finais de uma empresa PJ, preenchida automaticamente pela plataforma via consulta à Receita Federal.
MCC (Merchant Category Code)	Código de 4 dígitos que classifica o ramo de atividade do merchant, conforme padrão das bandeiras (Visa, Mastercard, etc.).
Acquirer Merchant Category Code	Código de subramo da Getnet, mais granular que o MCC. Define com mais precisão a atividade econômica do merchant.
CNAE	Classificação Nacional de Atividades Econômicas — código que identifica a atividade econômica de uma empresa perante a Receita Federal.
PEP (Pessoa Exposta Politicamente)	Pessoa que exerce ou exerceu cargo público relevante. A identificação de PEPs é exigida por regulamentação do Banco Central.
Domicílio Bancário	Conta bancária para a qual os valores recebidos pelo merchant são liquidados (transferidos).
Centralizadora	Merchant ou grupo que recebe a liquidação de pagamentos em nome de outros estabelecimentos subordinados.
Sub-status Steps	Etapas granulares do processo de onboarding (ex.: preenchimento de dados, validação de celular, envio de documentos), cada uma com seu próprio estado (`pending`, `finished`).
`merchant_id`	Identificador único do merchant gerado pela plataforma no momento da criação. Necessário para todas as operações subsequentes.
`acquirer_code`	Identificador do adquirente. Atualmente sempre `getnet`.
`fiscal_type`	Define se o merchant é Pessoa Física (`natural_person`) ou Pessoa Jurídica (`company`).
Opt-in	Consentimento explícito do merchant para o tratamento de dados (LGPD) e aceitação dos termos de uso. Obrigatório na criação do cadastro.
CEP de abrangência municipal	CEP que cobre um município inteiro, sem discriminar rua ou bairro. Nesses casos, os campos `street` e `district` devem ser informados manualmente.
DATA_GRID	Etapa do onboarding que agrupa os dados complementares ainda pendentes de preenchimento (renda, endereço, horário de funcionamento, etc.).
LETTER_OF_ATTORNEY	Etapa do onboarding exclusiva para PJ, referente ao envio da procuração quando o representante legal não é sócio da empresa.
SOCIAL_CONTRACT	Etapa do onboarding exclusiva para PJ, referente ao envio do contrato social da empresa.
Valores em centavos	Todos os campos monetários da API (renda, patrimônio, faturamento) são expressos em centavos. Exemplo: R$ 15.000,00 = `1500000`.
`approved` / `reproved`	Resultado da qualificação. `approved` indica que o merchant está apto a operar. `reproved` indica reprovação — o merchant não poderá realizar negócios com a Getnet.
`accepted`	Status do merchant logo após a criação, indicando que o cadastro foi recebido e está aguardando complemento de dados ou qualificação.
ISO 3166-1 alpha-2	Padrão internacional de códigos de país com 2 letras (ex.: `BR` para Brasil). Usado nos campos `country`, `nationality` e `country_of_birth`.

Nesta página

Merchants — Documentação Funcional