Payment Centralization

1. Overview

When a company has more than one establishment accredited with Getnet under the same CNPJ (or economic group), it may want to concentrate the receipt of all payments at a single point — or in a specific set of establishments. This mechanism is called payment centralization.

The Centralizers API allows you to check which establishments of a given CNPJ are already able to receive payments from other establishments in the group, that is, which can act as centralizers.

In business terms, this solves a very common problem in retail chains, franchises, and business groups: unifying the financial flow of multiple branches into a single account, making cash management, financial reconciliation, and receivables control easier.

2. Context and Use Cases

Use this service whenever you need to configure or validate the payment centralization structure of an economic group during the accreditation of new establishments.

Common Scenarios

Scenario	Description
Franchise network	The franchisor wants all payments from franchise units to be settled in the head office account.
Retail group with branches	A company with 10 stores wants 3 specific stores to receive the amounts from all others.
Accreditation of new branch	When registering a new store, you need to check which ECs in the group can be defined as centralizers for this new unit.
Financial structure audit	Check which ECs of a CNPJ are already configured as centralizers before making changes to the group.

3. Main Flow

The centralization flow involves two distinct moments: querying available centralizers and linking the centralized establishment, which is performed in the Merchants domain.

text

┌─────────────────────────────────────────────────────────────────┐
│                    CENTRALIZATION FLOW                          │
└─────────────────────────────────────────────────────────────────┘

  1. AUTHENTICATION
  ┌─────────────┐
  │  600;">POST       │
  │  /token     │  ──► Obtain the access token
  └─────────────┘
         │
         ▼
  2. QUERY CENTRALIZERS
  ┌──────────────────────────────────┐
  │  600;">GET /centralizers               │
  │  ?legal_document_number=CNPJ     │  ──► Lists the group&#039;s ECs that
  └──────────────────────────────────┘       can be centralizers
         │
         │  Returns a list of ECs with:
         │  - acquirer_merchant_code
         │  - merchant_name
         │  - current centralization_type
         │
         ▼
  3. LINK DEFINITION (Merchants domain)
  ┌───────────────────────────────────────────┐
  │  600;">PUT /merchants/{merchant_id}             │
  │  body: { centralization_data: {           │
  │    centralization_type: "centralized",    │
  │    centralizer_merchant: {                │
  │      acquirer_merchant_code: "EC000123"   │
  │    }                                      │
  │  }}                                       │
  └───────────────────────────────────────────┘
         │
         ▼
  ✔ Centralized merchant linked to the chosen centralizer

text

┌─────────────────────────────────────────────────────────────────┐
│                    CENTRALIZATION FLOW                          │
└─────────────────────────────────────────────────────────────────┘

  1. AUTHENTICATION
  ┌─────────────┐
  │  600;">POST       │
  │  /token     │  ──► Obtain the access token
  └─────────────┘
         │
         ▼
  2. QUERY CENTRALIZERS
  ┌──────────────────────────────────┐
  │  600;">GET /centralizers               │
  │  ?legal_document_number=CNPJ     │  ──► Lists the group&#039;s ECs that
  └──────────────────────────────────┘       can be centralizers
         │
         │  Returns a list of ECs with:
         │  - acquirer_merchant_code
         │  - merchant_name
         │  - current centralization_type
         │
         ▼
  3. LINK DEFINITION (Merchants domain)
  ┌───────────────────────────────────────────┐
  │  600;">PUT /merchants/{merchant_id}             │
  │  body: { centralization_data: {           │
  │    centralization_type: "centralized",    │
  │    centralizer_merchant: {                │
  │      acquirer_merchant_code: "EC000123"   │
  │    }                                      │
  │  }}                                       │
  └───────────────────────────────────────────┘
         │
         ▼
  ✔ Centralized merchant linked to the chosen centralizer

Note: The Centralizers API is only responsible for querying. The link between the merchant and its centralizer is recorded in the Merchants domain, through the CentralizationData object.

4. Prerequisites

Authentication

All endpoints of this API require a valid access token, obtained via the POST /token endpoint of the Authentication domain.

The token must be sent directly in the request header:

text

Authorization: {access_token}

text

Authorization: {access_token}

Do not use the Bearer prefix. The token must be provided directly, with no additional prefix.

Dependencies

Dependency	Purpose
Authentication API	Obtain the access token before any call.
Merchants API	Record the centralization link after identifying the desired centralizer.

Permissions

The token used must have access permission to the accreditation domain on the Getnet platform. Contact the integration team if you receive 401 errors.

5. Quick Integration Guide

Objective

Find out which establishments of a CNPJ can be centralizers for a new EC to be accredited.

Step 1 — Obtain the access token

Authenticate as described in the Authentication domain and save the returned access_token.

Step 2 — Query available centralizers

Send the group's CNPJ (digits only, 14 characters) as a query parameter:

Request

text

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

text

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

Expected response (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"
  }
]

Step 3 — Interpret the response

Each item in the list represents an EC in the group identified by the CNPJ. Analyze the centralization_type field to understand the current situation of each one:

centralizer → This EC is already a centralizer. It can receive payments from the new EC.
decentralized → This EC receives its own payments independently. It may be eligible to become a centralizer, depending on the enabled products.
centralized → This EC already has its payments directed to another centralizer.

Step 4 — Link the new EC to the chosen centralizer

With the acquirer_merchant_code of the desired centralizer in hand, use the Merchants API to register the centralization link in the new EC's record.

6. Business Rules

Product Rule (enabled brands)

The Centralizer EC must have all products enabled for the Centralized ECs.

The Centralized EC can have fewer products than the centralizer, but never more. If the Centralized EC has a brand that the centralizer does not have enabled, the accreditation will be rejected.

Products and covered modalities:

Product (Brand)	Covered modalities
Visa Debit	Debit, Recurring
Visa Credit	Credit, Installment, Recurring
Master Debit	Debit, Recurring
Master Credit	Credit, Installment, Recurring
Elo Debit	Debit, Recurring
Elo Credit	Credit, Installment, Recurring
Amex Credit	Credit, Installment, Recurring

Installment and Recurring are not independent products — they are modalities covered within the debit and credit functions of each brand.

`legal_document_number` field validations

Required field in the query.
Must contain exactly 14 numeric digits (no punctuation, dashes, or slashes).
Represents the CNPJ of the group to be queried.

Centralization types (`centralization_type`)

The field only accepts the following values:

Value	Meaning
`centralizer`	The EC concentrates receipts from other ECs in the group.
`centralized`	The EC has its receipts directed to a centralizer.
`decentralized`	The EC receives its own payments independently.

Centralizer identification in the link

When registering an EC as centralized in the Merchants API, the centralizer_merchant object becomes mandatory and must contain:

acquirer_merchant_code — code of the centralizer EC in Getnet.
legal_document_number — CNPJ of the centralizer EC (14 digits).

7. Error Handling

HTTP Code	Situation	What to do
400	The provided CNPJ is invalid (incorrect format, less or more than 14 digits, non-numeric characters).	Check the value sent in the `legal_document_number` parameter. Send only digits, no formatting.
401	Access token missing, expired, or invalid.	Re-authenticate via `POST /token` and use the new token in the request.
404	No centralizer found for the provided CNPJ.	Confirm that the CNPJ is correct and that the group already has ECs accredited with Getnet.
500	Internal server error at Getnet.	Wait a few moments and try again. If the error persists, contact Getnet support.

Example error response (400)

json

{
  "status_code": 400,
  "message": "findEcByLegalDocumentNumber.legalDocumentNumber: A valid document with 14 digits must be provided",
  "details": [
    {
      "field": "legal_document_number",
      "message": "A valid document with 14 digits must be provided."
    }
  ]
}

json

{
  "status_code": 400,
  "message": "findEcByLegalDocumentNumber.legalDocumentNumber: A valid document with 14 digits must be provided",
  "details": [
    {
      "field": "legal_document_number",
      "message": "A valid document with 14 digits must be provided."
    }
  ]
}

The details field lists each problematic field and its respective validation message, making it easier to identify the error in the payload.

8. Glossary

Term	Definition
EC (Commercial Establishment)	Any store, branch, or point of sale accredited with Getnet to accept payments.
CNPJ	National Registry of Legal Entities. Tax identification number for a company in Brazil, consisting of 14 digits.
Centralizer	EC that concentrates the receipt of payments from other ECs in the same economic group.
Centralized	EC whose receivables are directed to a centralizer EC.
Decentralized	EC that receives its own payments independently, without participating in a centralization structure.
Settlement	Process by which the value of an approved transaction is actually deposited in the establishment's account.
Receivable	Amount to be received by the EC for transactions carried out and approved.
acquirer_merchant_code	Unique code that identifies an EC on the Getnet (acquirer) platform.
Product	Combination of brand (e.g.: Visa, Master, Elo, Amex) and function (Debit or Credit) enabled for an EC.
Brand	Payment network responsible for processing the transaction (e.g.: Visa, Mastercard, Elo, American Express).
Installment	Credit installment modality with a specific financing plan, covered within the credit function.
Recurring	Automated periodic billing modality (e.g.: subscriptions), covered within the debit and credit functions.
CentralizationData	Object present in the Merchants domain that stores the centralization link of an EC (type and reference to the centralizer).
Access token	Temporary credential obtained via authentication, required to make authenticated API calls.

On this page

Payment Centralization

Payment Centralization

1. Overview

2. Context and Use Cases

Common Scenarios

3. Main Flow

4. Prerequisites

Authentication

Dependencies

Permissions

5. Quick Integration Guide

Objective

Step 1 — Obtain the access token

Step 2 — Query available centralizers

Step 3 — Interpret the response

Step 4 — Link the new EC to the chosen centralizer

6. Business Rules

Product Rule (enabled brands)

legal_document_number field validations

Centralization types (centralization_type)

Centralizer identification in the link

7. Error Handling

Example error response (400)

8. Glossary

`legal_document_number` field validations

Centralization types (`centralization_type`)