Centralização de Pagamento

1. Visão Geral

Quando uma empresa possui mais de um estabelecimento credenciado na Getnet sob o mesmo CNPJ (ou grupo econômico), ela pode querer concentrar o recebimento de todos os pagamentos em um único ponto — ou em um conjunto específico de estabelecimentos. Esse mecanismo é chamado de centralização de pagamento.

A API de Centralizadores permite consultar quais estabelecimentos de um determinado CNPJ já estão aptos a receber pagamentos de outros estabelecimentos do grupo, ou seja, quais podem atuar como centralizadores.

Em termos de negócio, isso resolve um problema muito comum em redes de varejo, franquias e grupos empresariais: unificar o fluxo financeiro de múltiplas filiais em uma única conta, facilitando a gestão do caixa, a conciliação financeira e o controle de recebíveis.

2. Contexto e Casos de Uso

Use este serviço sempre que precisar configurar ou validar a estrutura de centralização de pagamentos de um grupo econômico durante o credenciamento de novos estabelecimentos.

Cenários comuns

Cenário	Descrição
Rede de franquias	A franqueadora quer que todos os pagamentos das unidades franqueadas sejam liquidados na conta da matriz.
Grupo varejista com filiais	Uma empresa com 10 lojas deseja que 3 lojas específicas recebam os valores de todas as demais.
Credenciamento de nova filial	Ao cadastrar uma nova loja, é preciso consultar quais ECs do grupo podem ser definidos como centralizador dessa nova unidade.
Auditoria de estrutura financeira	Verificar quais ECs de um CNPJ já estão configurados como centralizadores antes de fazer alterações no grupo.

3. Fluxo Principal

O fluxo de centralização envolve dois momentos distintos: a consulta de centralizadores disponíveis e o vínculo do estabelecimento centralizado, que é realizado no domínio de Merchants.

text

┌─────────────────────────────────────────────────────────────────┐
│                    FLUXO DE CENTRALIZAÇÃO                       │
└─────────────────────────────────────────────────────────────────┘

  1. AUTENTICAÇÃO
  ┌─────────────┐
  │  600;">POST       │
  │  /token     │  ──► Obtém o token de acesso
  └─────────────┘
         │
         ▼
  2. CONSULTA DE CENTRALIZADORES
  ┌──────────────────────────────────┐
  │  600;">GET /centralizers               │
  │  ?legal_document_number=CNPJ     │  ──► Lista os ECs do grupo que
  └──────────────────────────────────┘       podem ser centralizadores
         │
         │  Retorna lista de ECs com:
         │  - acquirer_merchant_code
         │  - merchant_name
         │  - centralization_type atual
         │
         ▼
  3. DEFINIÇÃO DO VÍNCULO (domínio Merchants)
  ┌───────────────────────────────────────────┐
  │  600;">PUT /merchants/{merchant_id}             │
  │  body: { centralization_data: {           │
  │    centralization_type: "centralized",    │
  │    centralizer_merchant: {                │
  │      acquirer_merchant_code: "EC000123"   │
  │    }                                      │
  │  }}                                       │
  └───────────────────────────────────────────┘
         │
         ▼
  ✔ Merchant centralizado vinculado ao centralizador escolhido

text

┌─────────────────────────────────────────────────────────────────┐
│                    FLUXO DE CENTRALIZAÇÃO                       │
└─────────────────────────────────────────────────────────────────┘

  1. AUTENTICAÇÃO
  ┌─────────────┐
  │  600;">POST       │
  │  /token     │  ──► Obtém o token de acesso
  └─────────────┘
         │
         ▼
  2. CONSULTA DE CENTRALIZADORES
  ┌──────────────────────────────────┐
  │  600;">GET /centralizers               │
  │  ?legal_document_number=CNPJ     │  ──► Lista os ECs do grupo que
  └──────────────────────────────────┘       podem ser centralizadores
         │
         │  Retorna lista de ECs com:
         │  - acquirer_merchant_code
         │  - merchant_name
         │  - centralization_type atual
         │
         ▼
  3. DEFINIÇÃO DO VÍNCULO (domínio Merchants)
  ┌───────────────────────────────────────────┐
  │  600;">PUT /merchants/{merchant_id}             │
  │  body: { centralization_data: {           │
  │    centralization_type: "centralized",    │
  │    centralizer_merchant: {                │
  │      acquirer_merchant_code: "EC000123"   │
  │    }                                      │
  │  }}                                       │
  └───────────────────────────────────────────┘
         │
         ▼
  ✔ Merchant centralizado vinculado ao centralizador escolhido

Atenção: A API de Centralizadores é responsável apenas pela consulta. O vínculo entre o merchant e seu centralizador é gravado no domínio Merchants, por meio do objeto CentralizationData.

4. Pré-requisitos

Autenticação

Todos os endpoints desta API exigem um token de acesso válido, obtido pelo endpoint POST /token do domínio de Autenticação.

O token deve ser enviado diretamente no cabeçalho da requisição:

text

Authorization: {access_token}

text

Authorization: {access_token}

Não utilize o prefixo Bearer. O token deve ser informado diretamente, sem nenhum prefixo adicional.

Dependências

Dependência	Finalidade
API de Autenticação	Obtenção do token de acesso antes de qualquer chamada.
API de Merchants	Gravação do vínculo de centralização após identificar o centralizador desejado.

Permissões

O token utilizado deve ter permissão de acesso ao domínio de credenciamento na plataforma Getnet. Consulte a equipe de integração caso receba erros 401.

5. Guia de Integração Rápida

Objetivo

Descobrir quais estabelecimentos de um CNPJ podem ser centralizadores para um novo EC a ser credenciado.

Passo 1 — Obtenha o token de acesso

Realize a autenticação conforme descrito no domínio de Autenticação e guarde o access_token retornado.

Passo 2 — Consulte os centralizadores disponíveis

Envie o CNPJ do grupo (somente dígitos, 14 caracteres) como parâmetro de consulta:

Requisição

text

600;">GET /v1/centralizers?legal_document_number=12345678000199
Authorization: {access_token}

text

600;">GET /v1/centralizers?legal_document_number=12345678000199
Authorization: {access_token}

Resposta esperada (HTTP 200)

json

[
  {
    "legal_document_number": "12345678000199",
    "acquirer_merchant_code": "EC00012345",
    "merchant_name": "Loja Matriz Ltda.",
    "centralization_type": "centralizer"
  },
  {
    "legal_document_number": "12345678000280",
    "acquirer_merchant_code": "EC00012346",
    "merchant_name": "Filial Centro",
    "centralization_type": "decentralized"
  }
]

json

[
  {
    "legal_document_number": "12345678000199",
    "acquirer_merchant_code": "EC00012345",
    "merchant_name": "Loja Matriz Ltda.",
    "centralization_type": "centralizer"
  },
  {
    "legal_document_number": "12345678000280",
    "acquirer_merchant_code": "EC00012346",
    "merchant_name": "Filial Centro",
    "centralization_type": "decentralized"
  }
]

Passo 3 — Interprete o retorno

Cada item da lista representa um EC do grupo identificado pelo CNPJ. Analise o campo centralization_type para entender a situação atual de cada um:

centralizer → Este EC já é um centralizador. Ele pode receber os pagamentos do novo EC.
decentralized → Este EC recebe seus próprios pagamentos de forma independente. Pode ser elegível a se tornar centralizador, dependendo dos produtos habilitados.
centralized → Este EC já tem seus pagamentos direcionados a outro centralizador.

Passo 4 — Vincule o novo EC ao centralizador escolhido

Com o acquirer_merchant_code do centralizador desejado em mãos, utilize a API de Merchants para registrar o vínculo de centralização no cadastro do novo EC.

6. Regras de Negócio

Regra de Produtos (bandeiras habilitadas)

O EC Centralizador deve possuir todos os produtos habilitados para os ECs Centralizados.

O EC Centralizado pode ter menos produtos que o centralizador, mas nunca mais. Caso o EC Centralizado possua uma bandeira que o centralizador não tem habilitada, o credenciamento será rejeitado.

Produtos e modalidades contempladas:

Produto (Bandeira)	Modalidades contempladas
Visa Débito	Débito, Recorrente
Visa Crédito	Crédito, Crediário, Recorrente
Master Débito	Débito, Recorrente
Master Crédito	Crédito, Crediário, Recorrente
Elo Débito	Débito, Recorrente
Elo Crédito	Crédito, Crediário, Recorrente
Amex Crédito	Crédito, Crediário, Recorrente

Crediário e Recorrente não são produtos independentes — eles são modalidades contempladas dentro das funções de débito e crédito de cada bandeira.

Validações do campo `legal_document_number`

Campo obrigatório na consulta.
Deve conter exatamente 14 dígitos numéricos (sem pontuação, traços ou barras).
Representa o CNPJ do grupo a ser consultado.

Tipos de centralização (`centralization_type`)

O campo aceita apenas os seguintes valores:

Valor	Significado
`centralizer`	O EC concentra recebimentos de outros ECs do grupo.
`centralized`	O EC tem seus recebimentos direcionados a um centralizador.
`decentralized`	O EC recebe seus próprios pagamentos de forma independente.

Identificação do centralizador no vínculo

Ao registrar um EC como centralized na API de Merchants, o objeto centralizer_merchant torna-se obrigatório e deve conter:

acquirer_merchant_code — código do EC centralizador na Getnet.
legal_document_number — CNPJ do EC centralizador (14 dígitos).

7. Tratamento de Erros

Código HTTP	Situação	O que fazer
400	O CNPJ informado é inválido (formato incorreto, menos ou mais de 14 dígitos, caracteres não numéricos).	Verifique o valor enviado no parâmetro `legal_document_number`. Envie somente dígitos, sem formatação.
401	Token de acesso ausente, expirado ou inválido.	Refaça a autenticação via `POST /token` e utilize o novo token na requisição.
404	Nenhum centralizador encontrado para o CNPJ informado.	Confirme se o CNPJ está correto e se o grupo já possui ECs credenciados na Getnet.
500	Erro interno no servidor da Getnet.	Aguarde alguns instantes e tente novamente. Se o erro persistir, acione o suporte Getnet.

Exemplo de resposta de erro (400)

json

{
  "status_code": 400,
  "message": "findEcByLegalDocumentNumber.legalDocumentNumber: Deve ser informado um documento válido com 14 digitos",
  "details": [
    {
      "field": "legal_document_number",
      "message": "Deve ser informado um documento válido com 14 dígitos."
    }
  ]
}

json

{
  "status_code": 400,
  "message": "findEcByLegalDocumentNumber.legalDocumentNumber: Deve ser informado um documento válido com 14 digitos",
  "details": [
    {
      "field": "legal_document_number",
      "message": "Deve ser informado um documento válido com 14 dígitos."
    }
  ]
}

O campo details lista cada campo com problema e sua respectiva mensagem de validação, facilitando a identificação do erro no payload.

8. Glossário

Termo	Definição
EC (Estabelecimento Comercial)	Qualquer loja, filial ou ponto de venda credenciado na Getnet para aceitar pagamentos.
CNPJ	Cadastro Nacional de Pessoa Jurídica. Número de identificação fiscal de uma empresa no Brasil, composto por 14 dígitos.
Centralizador	EC que concentra o recebimento dos pagamentos de outros ECs do mesmo grupo econômico.
Centralizado	EC cujos recebíveis são direcionados para um EC centralizador.
Descentralizado	EC que recebe seus próprios pagamentos de forma independente, sem participar de uma estrutura de centralização.
Liquidação	Processo pelo qual o valor de uma transação aprovada é efetivamente depositado na conta do estabelecimento.
Recebível	Valor a ser recebido pelo EC referente a transações realizadas e aprovadas.
acquirer_merchant_code	Código único que identifica um EC na plataforma da Getnet (adquirente).
Produto	Combinação de bandeira (ex.: Visa, Master, Elo, Amex) e função (Débito ou Crédito) habilitada para um EC.
Bandeira	Rede de pagamento responsável pelo processamento da transação (ex.: Visa, Mastercard, Elo, American Express).
Crediário	Modalidade de parcelamento do crédito com plano de financiamento específico, contemplada dentro da função crédito.
Recorrente	Modalidade de cobrança periódica automatizada (ex.: assinaturas), contemplada dentro das funções débito e crédito.
CentralizationData	Objeto presente no domínio Merchants que armazena o vínculo de centralização de um EC (tipo e referência ao centralizador).
Token de acesso	Credencial temporária obtida via autenticação, necessária para realizar chamadas autenticadas à API.

On this page

Centralização de Pagamento

Centralização de Pagamento

1. Visão Geral

2. Contexto e Casos de Uso

Cenários comuns

3. Fluxo Principal

4. Pré-requisitos

Autenticação

Dependências

Permissões

5. Guia de Integração Rápida

Objetivo

Passo 1 — Obtenha o token de acesso

Passo 2 — Consulte os centralizadores disponíveis

Passo 3 — Interprete o retorno

Passo 4 — Vincule o novo EC ao centralizador escolhido

6. Regras de Negócio

Regra de Produtos (bandeiras habilitadas)

Validações do campo legal_document_number

Tipos de centralização (centralization_type)

Identificação do centralizador no vínculo

7. Tratamento de Erros

Exemplo de resposta de erro (400)

8. Glossário

Validações do campo `legal_document_number`

Tipos de centralização (`centralization_type`)