Centralización de Pagos

1. Visión General

Cuando una empresa tiene más de un establecimiento acreditado en Getnet bajo el mismo CNPJ (o grupo económico), puede querer concentrar la recepción de todos los pagos en un único punto —o en un conjunto específico de establecimientos. Este mecanismo se llama centralización de pagos.

La API de Centralizadores permite consultar qué establecimientos de un determinado CNPJ ya están aptos para recibir pagos de otros establecimientos del grupo, es decir, cuáles pueden actuar como centralizadores.

En términos de negocio, esto resuelve un problema muy común en redes de comercios, franquicias y grupos empresariales: unificar el flujo financiero de múltiples sucursales en una sola cuenta, facilitando la gestión de caja, la conciliación financiera y el control de cuentas por cobrar.

2. Contexto y Casos de Uso

Utiliza este servicio siempre que necesites configurar o validar la estructura de centralización de pagos de un grupo económico durante la acreditación de nuevos establecimientos.

Escenarios comunes

Escenario	Descripción
Red de franquicias	La franquiciadora quiere que todos los pagos de las unidades franquiciadas se liquiden en la cuenta de la matriz.
Grupo minorista con sucursales	Una empresa con 10 tiendas desea que 3 tiendas específicas reciban los valores de todas las demás.
Acreditación de nueva sucursal	Al registrar una nueva tienda, es necesario consultar qué ECs del grupo pueden ser definidos como centralizadores de esa nueva unidad.
Auditoría de estructura financiera	Verificar qué ECs de un CNPJ ya están configurados como centralizadores antes de hacer cambios en el grupo.

3. Flujo Principal

El flujo de centralización involucra dos momentos distintos: la consulta de centralizadores disponibles y el vínculo del establecimiento centralizado, que se realiza en el dominio de Merchants.

text

┌─────────────────────────────────────────────────────────────────┐
│                    FLUJO DE CENTRALIZACIÓN                      │
└─────────────────────────────────────────────────────────────────┘

  1. AUTENTICACIÓN
  ┌─────────────┐
  │  600;">POST       │
  │  /token     │  ──► Obtiene el token de acceso
  └─────────────┘
         │
         ▼
  2. CONSULTA DE CENTRALIZADORES
  ┌──────────────────────────────────┐
  │  600;">GET /centralizers               │
  │  ?legal_document_number=CNPJ     │  ──► Lista los ECs del grupo que
  └──────────────────────────────────┘       pueden ser centralizadores
         │
         │  Devuelve lista de ECs con:
         │  - acquirer_merchant_code
         │  - merchant_name
         │  - centralization_type actual
         │
         ▼
  3. DEFINICIÓN DEL VÍNCULO (dominio Merchants)
  ┌───────────────────────────────────────────┐
  │  600;">PUT /merchants/{merchant_id}             │
  │  body: { centralization_data: {           │
  │    centralization_type: "centralized",    │
  │    centralizer_merchant: {                │
  │      acquirer_merchant_code: "EC000123"   │
  │    }                                      │
  │  }}                                       │
  └───────────────────────────────────────────┘
         │
         ▼
  ✔ Comercio centralizado vinculado al centralizador elegido

text

┌─────────────────────────────────────────────────────────────────┐
│                    FLUJO DE CENTRALIZACIÓN                      │
└─────────────────────────────────────────────────────────────────┘

  1. AUTENTICACIÓN
  ┌─────────────┐
  │  600;">POST       │
  │  /token     │  ──► Obtiene el token de acceso
  └─────────────┘
         │
         ▼
  2. CONSULTA DE CENTRALIZADORES
  ┌──────────────────────────────────┐
  │  600;">GET /centralizers               │
  │  ?legal_document_number=CNPJ     │  ──► Lista los ECs del grupo que
  └──────────────────────────────────┘       pueden ser centralizadores
         │
         │  Devuelve lista de ECs con:
         │  - acquirer_merchant_code
         │  - merchant_name
         │  - centralization_type actual
         │
         ▼
  3. DEFINICIÓN DEL VÍNCULO (dominio Merchants)
  ┌───────────────────────────────────────────┐
  │  600;">PUT /merchants/{merchant_id}             │
  │  body: { centralization_data: {           │
  │    centralization_type: "centralized",    │
  │    centralizer_merchant: {                │
  │      acquirer_merchant_code: "EC000123"   │
  │    }                                      │
  │  }}                                       │
  └───────────────────────────────────────────┘
         │
         ▼
  ✔ Comercio centralizado vinculado al centralizador elegido

Atención: La API de Centralizadores es responsable solo por la consulta. El vínculo entre el comercio y su centralizador se graba en el dominio Merchants, mediante el objeto CentralizationData.

4. Prerrequisitos

Autenticación

Todos los endpoints de esta API requieren un token de acceso válido, obtenido por el endpoint POST /token del dominio de Autenticación.

El token debe enviarse directamente en el encabezado de la solicitud:

text

Authorization: {access_token}

text

Authorization: {access_token}

No utilices el prefijo Bearer. El token debe informarse directamente, sin ningún prefijo adicional.

Dependencias

Dependencia	Finalidad
API de Autenticación	Obtención del token de acceso antes de cualquier llamada.
API de Merchants	Grabación del vínculo de centralización tras identificar el centralizador deseado.

Permisos

El token utilizado debe tener permiso de acceso al dominio de acreditación en la plataforma Getnet. Consulta al equipo de integración si recibes errores 401.

5. Guía Rápida de Integración

Objetivo

Descubrir qué establecimientos de un CNPJ pueden ser centralizadores para un nuevo EC a acreditar.

Paso 1 — Obtén el token de acceso

Realiza la autenticación como se describe en el dominio de Autenticación y guarda el access_token retornado.

Paso 2 — Consulta los centralizadores disponibles

Envía el CNPJ del grupo (solo dígitos, 14 caracteres) como parámetro de consulta:

Solicitud

text

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

text

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

Respuesta 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"
  }
]

Paso 3 — Interpreta la respuesta

Cada elemento de la lista representa un EC del grupo identificado por el CNPJ. Analiza el campo centralization_type para entender la situación actual de cada uno:

centralizer → Este EC ya es un centralizador. Puede recibir los pagos del nuevo EC.
decentralized → Este EC recibe sus propios pagos de forma independiente. Puede ser elegible para convertirse en centralizador, dependiendo de los productos habilitados.
centralized → Este EC ya tiene sus pagos dirigidos a otro centralizador.

Paso 4 — Vincula el nuevo EC al centralizador elegido

Con el acquirer_merchant_code del centralizador deseado en mano, utiliza la API de Merchants para registrar el vínculo de centralización en el registro del nuevo EC.

6. Reglas de Negocio

Regla de Productos (marcas habilitadas)

El EC Centralizador debe poseer todos los productos habilitados para los ECs Centralizados.

El EC Centralizado puede tener menos productos que el centralizador, pero nunca más. Si el EC Centralizado posee una marca que el centralizador no tiene habilitada, la acreditación será rechazada.

Productos y modalidades contempladas:

Producto (Marca)	Modalidades contempladas
Visa Débito	Débito, Recurrente
Visa Crédito	Crédito, Cuotas, Recurrente
Master Débito	Débito, Recurrente
Master Crédito	Crédito, Cuotas, Recurrente
Elo Débito	Débito, Recurrente
Elo Crédito	Crédito, Cuotas, Recurrente
Amex Crédito	Crédito, Cuotas, Recurrente

Cuotas y Recurrente no son productos independientes — son modalidades contempladas dentro de las funciones de débito y crédito de cada marca.

Validaciones del campo `legal_document_number`

Campo obligatorio en la consulta.
Debe contener exactamente 14 dígitos numéricos (sin puntuación, guiones ni barras).
Representa el CNPJ del grupo a consultar.

Tipos de centralización (`centralization_type`)

El campo acepta solo los siguientes valores:

Valor	Significado
`centralizer`	El EC concentra los cobros de otros ECs del grupo.
`centralized`	El EC tiene sus cobros dirigidos a un centralizador.
`decentralized`	El EC recibe sus propios pagos de forma independiente.

Identificación del centralizador en el vínculo

Al registrar un EC como centralized en la API de Merchants, el objeto centralizer_merchant se vuelve obligatorio y debe contener:

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

7. Manejo de Errores

Código HTTP	Situación	Qué hacer
400	El CNPJ informado es inválido (formato incorrecto, menos o más de 14 dígitos, caracteres no numéricos).	Verifica el valor enviado en el parámetro `legal_document_number`. Envía solo dígitos, sin formato.
401	Token de acceso ausente, expirado o inválido.	Realiza nuevamente la autenticación vía `POST /token` y utiliza el nuevo token en la solicitud.
404	No se encontró centralizador para el CNPJ informado.	Confirma que el CNPJ es correcto y que el grupo ya tiene ECs acreditados en Getnet.
500	Error interno en el servidor de Getnet.	Espera unos instantes e inténtalo de nuevo. Si el error persiste, contacta al soporte de Getnet.

Ejemplo de respuesta de error (400)

json

{
  "status_code": 400,
  "message": "findEcByLegalDocumentNumber.legalDocumentNumber: Debe informarse un documento válido con 14 dígitos",
  "details": [
    {
      "field": "legal_document_number",
      "message": "Debe informarse un documento válido con 14 dígitos."
    }
  ]
}

json

{
  "status_code": 400,
  "message": "findEcByLegalDocumentNumber.legalDocumentNumber: Debe informarse un documento válido con 14 dígitos",
  "details": [
    {
      "field": "legal_document_number",
      "message": "Debe informarse un documento válido con 14 dígitos."
    }
  ]
}

El campo details lista cada campo con problema y su respectivo mensaje de validación, facilitando la identificación del error en el payload.

8. Glosario

Término	Definición
EC (Establecimiento Comercial)	Cualquier tienda, sucursal o punto de venta acreditado en Getnet para aceptar pagos.
CNPJ	Registro Nacional de Personas Jurídicas. Número de identificación fiscal de una empresa en Brasil, compuesto por 14 dígitos.
Centralizador	EC que concentra la recepción de pagos de otros ECs del mismo grupo económico.
Centralizado	EC cuyos cobros se dirigen a un EC centralizador.
Descentralizado	EC que recibe sus propios pagos de forma independiente, sin participar en una estructura de centralización.
Liquidación	Proceso por el cual el valor de una transacción aprobada se deposita efectivamente en la cuenta del establecimiento.
Cuenta por cobrar	Valor a recibir por el EC referente a transacciones realizadas y aprobadas.
acquirer_merchant_code	Código único que identifica un EC en la plataforma de Getnet (adquirente).
Producto	Combinación de marca (ej.: Visa, Master, Elo, Amex) y función (Débito o Crédito) habilitada para un EC.
Marca	Red de pago responsable del procesamiento de la transacción (ej.: Visa, Mastercard, Elo, American Express).
Cuotas	Modalidad de pago en cuotas con plan de financiamiento específico, contemplada dentro de la función crédito.
Recurrente	Modalidad de cobro periódico automatizado (ej.: suscripciones), contemplada dentro de las funciones débito y crédito.
CentralizationData	Objeto presente en el dominio Merchants que almacena el vínculo de centralización de un EC (tipo y referencia al centralizador).
Token de acceso	Credencial temporal obtenida vía autenticación, necesaria para realizar llamadas autenticadas a la API.

En esta página

Centralización de Pagos

Centralización de Pagos

1. Visión General

2. Contexto y Casos de Uso

Escenarios comunes

3. Flujo Principal

4. Prerrequisitos

Autenticación

Dependencias

Permisos

5. Guía Rápida de Integración

Objetivo

Paso 1 — Obtén el token de acceso

Paso 2 — Consulta los centralizadores disponibles

Paso 3 — Interpreta la respuesta

Paso 4 — Vincula el nuevo EC al centralizador elegido

6. Reglas de Negocio

Regla de Productos (marcas habilitadas)

Validaciones del campo legal_document_number

Tipos de centralización (centralization_type)

Identificación del centralizador en el vínculo

7. Manejo de Errores

Ejemplo de respuesta de error (400)

8. Glosario

Validaciones del campo `legal_document_number`

Tipos de centralización (`centralization_type`)