Banks — Bank Domicile

1. Overview

The Banks service allows you to check which financial institutions are available to receive the amounts from transactions carried out by merchants accredited with Getnet.

When an establishment is accredited, it must provide a bank account where the payments from its sales will be deposited. This link is called a bank domicile. This service is the starting point for that choice: it provides the list of banks accepted by Getnet and indicates whether each bank is able to receive from all card brands with which Getnet operates.

Without this step, it is not possible to guarantee that the merchant will correctly receive the amounts from all their sales.

2. Context and Use Cases

When to use

This service should be used during the merchant accreditation journey, at the stage where the user needs to select the bank in which they wish to receive their payments.

⚠️ Important: Channels linked to already established banks or credit unions that have their own checking account do not use this service. In these cases, the bank account is already known and predefined by the channel itself, being informed directly in the accreditation without the need for consultation.

Usage scenarios

Scenario	Description
Accreditation of new merchant	The operator needs to display to the user the list of available banks for choosing the bank domicile.
Brand coverage validation	After choosing the bank, check if it accepts receivables from all brands (VISA, MASTER, ELO, AMEX).
Indication of complementary bank	When the chosen bank does not cover all brands, guide the user to indicate a second bank for the remaining brands.

3. Main Flow

The service consists of two endpoints that should be used in sequence during accreditation:

text

┌─────────────────────────────────────────────────────────────┐
│                  BANK DOMICILE SELECTION                    │
└─────────────────────────────────────────────────────────────┘

   STEP 1                  STEP 2                 STEP 3
┌──────────────┐       ┌──────────────────┐      ┌─────────────────────┐
│ 600;">GET /banks   │──────▶│ 600;">GET /banks/      │─────▶│ Register bank       │
│              │       │ {bank_code}/     │      │ domicile in merchant│
│ List all     │       │ not-allowed-     │      │ (Merchants domain)  │
│ available    │       │ brands           │      └─────────��───────────┘
│ banks        │       │                  │
└──────────────┘       │ Check if the     │
                       │ bank covers all  │
                       │ brands           │
                       └────────┬─────────┘
                                │
               ┌────────────────┴────────────────┐
               │                                 │
               ▼                                 ▼
     brands: [] (empty)               brands: ["MASTER", "ELO", ...]
               │                                 │
    ┌──────────┴──────────┐          ┌───────────┴──────────────┐
    │  Bank covers all    │          │  Bank does NOT cover     │
    │  brands.            │          │  all brands.             │
    │  Proceed with       │          │                          │
    │  single bank.       │          │  Indicate a SECOND bank  │
    └─────────────────────┘          │  able to cover the       │
                                     │  uncovered brands.       │
                                     └──────────────────────────┘
                                               │
                                  ┌────────────┴────────────┐
                                  │                         │
                                  ▼                         ▼
                        Second bank                Second bank NOT
                        informed.                  informed.
                        Receivables                Receivables from
                        guaranteed for             uncovered brands
                        all brands.                are HELD until
                                                   regularization.

text

┌─────────────────────────────────────────────────────────────┐
│                  BANK DOMICILE SELECTION                    │
└─────────────────────────────────────────────────────────────┘

   STEP 1                  STEP 2                 STEP 3
┌──────────────┐       ┌──────────────────┐      ┌─────────────────────┐
│ 600;">GET /banks   │──────▶│ 600;">GET /banks/      │─────▶│ Register bank       │
│              │       │ {bank_code}/     │      │ domicile in merchant│
│ List all     │       │ not-allowed-     │      │ (Merchants domain)  │
│ available    │       │ brands           │      └─────────��───────────┘
│ banks        │       │                  │
└──────────────┘       │ Check if the     │
                       │ bank covers all  │
                       │ brands           │
                       └────────┬─────────┘
                                │
               ┌────────────────┴────────────────┐
               │                                 │
               ▼                                 ▼
     brands: [] (empty)               brands: ["MASTER", "ELO", ...]
               │                                 │
    ┌──────────┴──────────┐          ┌───────────┴──────────────┐
    │  Bank covers all    │          │  Bank does NOT cover     │
    │  brands.            │          │  all brands.             │
    │  Proceed with       │          │                          │
    │  single bank.       │          │  Indicate a SECOND bank  │
    └─────────────────────┘          │  able to cover the       │
                                     │  uncovered brands.       │
                                     └──────────────────────────┘
                                               │
                                  ┌────────────┴────────────┐
                                  │                         │
                                  ▼                         ▼
                        Second bank                Second bank NOT
                        informed.                  informed.
                        Receivables                Receivables from
                        guaranteed for             uncovered brands
                        all brands.                are HELD until
                                                   regularization.

Step by step

Step 1 — List available banks Call GET /v1/banks to get the full list of eligible banks. Filter and display to the user only banks with situation.status = "active". The most relevant fields for display are bank_name (bank name) and bank_code (FEBRABAN code).

Step 2 — Check brand coverage With the bank_code of the bank chosen by the user, call GET /v1/banks/{bank_code}/not-allowed-brands. The return will indicate if the bank has any brand restrictions.

Step 3 — Register the bank domicile With the selected bank(s), register the merchant's bank domicile through the Merchants domain (MerchantAccount resource).

4. Prerequisites

Authentication

All endpoints require an access token previously obtained via:

text

POST /v1/token

text

POST /v1/token

The token must be sent in the header of each request:

text

Authorization: {access_token}

text

Authorization: {access_token}

No Bearer prefix is required. The token is sent directly.

Dependencies

Dependency	Description
Authentication Service	The access token must be obtained before any call to this domain. See the Authentication documentation.
Merchants Domain	The resulting bank domicile from this selection is registered in the Merchants domain. This service only assists in bank consultation and validation.

Profiles and permissions

Access to this service is restricted to channels and operators with permission to accredit merchants on the Getnet platform.

5. Quick Integration Guide

Scenario: select bank and validate brand coverage

Step 1 — Get the list of banks

text

600;">GET /v1/banks
Authorization: {token}

text

600;">GET /v1/banks
Authorization: {token}

Expected return (partial):

json

[
  {
    "bank_id": "5c253d4ceaf123cc51dd10ad",
    "bank_name": "BANCO SANTANDER (BRASIL) S.A.",
    "bank_country": "BR",
    "bank_code": "033",
    "situation": {
      "status": "active"
    }
  },
  {
    "bank_id": "5c253d4c7c840577fc6f194a",
    "bank_name": "BANCO BRADESCO S.A.",
    "bank_country": "BR",
    "bank_code": "237",
    "situation": {
      "status": "active"
    }
  }
]

json

[
  {
    "bank_id": "5c253d4ceaf123cc51dd10ad",
    "bank_name": "BANCO SANTANDER (BRASIL) S.A.",
    "bank_country": "BR",
    "bank_code": "033",
    "situation": {
      "status": "active"
    }
  },
  {
    "bank_id": "5c253d4c7c840577fc6f194a",
    "bank_name": "BANCO BRADESCO S.A.",
    "bank_country": "BR",
    "bank_code": "237",
    "situation": {
      "status": "active"
    }
  }
]

✅ Display to the user only banks with status: "active". Use bank_name for visual identification and bank_code for the next calls.

Step 2 — Check brands of the selected bank

Suppose the user chose Bradesco (bank_code: "237"):

text

600;">GET /v1/banks/237/not-allowed-brands
Authorization: {token}

text

600;">GET /v1/banks/237/not-allowed-brands
Authorization: {token}

Return — bank without restrictions:

json

{
  "bank_code": "033",
  "bank_name": "",
  "brands": []
}

json

{
  "bank_code": "033",
  "bank_name": "",
  "brands": []
}

✅ The brands field is empty: the bank accepts receivables from all brands. Proceed normally.

Return — bank with restrictions:

json

{
  "bank_code": "237",
  "bank_name": "BANCO BRADESCO S.A.",
  "brands": [
    "MASTER",
    "CARTAO AMEX"
  ]
}

json

{
  "bank_code": "237",
  "bank_name": "BANCO BRADESCO S.A.",
  "brands": [
    "MASTER",
    "CARTAO AMEX"
  ]
}

⚠️ The bank does not accept receivables from MASTER and AMEX. In this case, guide the user to select a second bank that covers these brands. The second bank must be validated in the same way (Step 2) to ensure it covers the missing brands.

6. Business Rules

Bank eligibility

Only banks with situation.status = "active" are available for bank domicile selection.
Banks with status "deactivated" must not be displayed to the user nor used in accreditation.

Brands supported by Getnet

Getnet operates with four acquiring brands (ADQ):

Brand	Identification in the API return
VISA	`VISA`
Mastercard	`MASTER`
Elo	`ELO`
American Express	`CARTAO AMEX`

Mandatory complementary bank

When the main bank does not cover all brands, it is necessary to indicate a second bank for the uncovered brands.
The second bank must be able to receive from the specific brands that the first one does not cover.
If the second bank is not informed, the receivables from the uncovered brands will remain held indefinitely, until an enabled bank is registered.

Channels with their own bank

Channels linked to already established banks or credit unions that have their own checking account must not use this service. The bank domicile of these channels is predefined by the institution itself and informed directly in the accreditation.

Mandatory fields in the `Bank` schema

Field	Requirement	Description
`bank_code`	Mandatory	Bank FEBRABAN clearing code.
`bank_country`	Mandatory	Bank country (ISO 3166-1 alpha-2). Currently only `BR`.

7. Error Handling

HTTP Code	Meaning	What to do
`400` Bad Request	The request was sent with invalid or malformed parameters.	Check the parameters sent (e.g.: `bank_code` with invalid format, `country` outside the ISO standard).
`401` Unauthorized	The authentication token is missing, invalid or expired.	Obtain a new token via `POST /v1/token` and resend the request.
`404` Not Found	The bank informed in the request path was not found.	Check if the `bank_code` used was correctly obtained via `GET /v1/banks` and if it corresponds to an active bank.
`500` Internal Server Error	Internal error in the Getnet platform.	Wait a few moments and try again. If the problem persists, contact Getnet support.

8. Glossary

Term	Definition
Bank domicile	Bank account registered by the merchant to receive the amounts from its sales. Each brand may have a different bank domicile.
Bank code	Bank clearing code, controlled by FEBRABAN in Brazil. It is the identifier used to reference the bank in API calls.
Brand (ADQ)	Payment network responsible for processing card transactions (e.g.: VISA, MASTER, ELO, AMEX). Each brand may have different settlement rules.
Complementary bank	Second bank indicated by the merchant to receive the receivables from brands that the main bank does not cover.
Status active	Indicates that the bank is active and available for use as a bank domicile at Getnet.
Status deactivated	Indicates that the bank has been deactivated and cannot be used for new bank domiciles.
Held receivables	Sales amounts that cannot be settled due to the absence of a bank enabled to receive from the corresponding brand. They remain blocked until an eligible bank is registered.
Channel	Partner or institution that accredits merchants on the Getnet platform (e.g.: bank, credit union, commercial agent).
FEBRABAN	Brazilian Federation of Banks. Body responsible for registering and assigning bank clearing codes in Brazil.
Merchant	Commercial establishment accredited with Getnet to accept card payments.

On this page

Banks — Bank Domicile

Banks — Bank Domicile

1. Overview

2. Context and Use Cases

When to use

Usage scenarios

3. Main Flow

Step by step

4. Prerequisites

Authentication

Dependencies

Profiles and permissions

5. Quick Integration Guide

Scenario: select bank and validate brand coverage

Step 1 — Get the list of banks

Step 2 — Check brands of the selected bank

6. Business Rules

Bank eligibility

Brands supported by Getnet

Mandatory complementary bank

Channels with their own bank

Mandatory fields in the Bank schema

7. Error Handling

8. Glossary

Mandatory fields in the `Bank` schema