Bancos — Domicílio Bancário
1. Visão Geral
O serviço de Bancos permite consultar quais instituições financeiras estão disponíveis para receber os valores das transações realizadas pelos merchants credenciados na Getnet.
Quando um estabelecimento é credenciado, ele precisa informar uma conta bancária para onde os pagamentos das suas vendas serão depositados. Esse vínculo é chamado de domicílio bancário. Este serviço é o ponto de partida para essa escolha: ele fornece a lista de bancos aceitos pela Getnet e indica se cada banco é capaz de receber de todas as bandeiras de cartão com as quais a Getnet opera.
Sem essa etapa, não é possível garantir que o merchant receberá corretamente os valores de todas as suas vendas.
2. Contexto e Casos de Uso
Quando usar
Este serviço deve ser utilizado durante a jornada de credenciamento de um merchant, na etapa em que o usuário precisa selecionar o banco no qual deseja receber seus pagamentos.
⚠️ Importante: Canais vinculados a bancos já estabelecidos ou a cooperativas de crédito que possuam conta corrente própria não utilizam este serviço. Nesses casos, a conta bancária já é conhecida e predefinida pelo próprio canal, sendo informada diretamente no credenciamento sem necessidade de consulta.
Cenários de uso
| Cenário | Descrição |
|---|---|
| Credenciamento de novo merchant | O operador precisa exibir ao usuário a lista de bancos disponíveis para escolha do domicílio bancário. |
| Validação de cobertura de bandeiras | Após a escolha do banco, verificar se ele aceita recebíveis de todas as bandeiras (VISA, MASTER, ELO, AMEX). |
| Indicação de banco complementar | Quando o banco escolhido não cobre todas as bandeiras, orientar o usuário a indicar um segundo banco para as bandeiras restantes. |
3. Fluxo Principal
O serviço é composto por dois endpoints que devem ser utilizados em sequência durante o credenciamento:
text
┌─────────────────────────────────────────────────────────────┐
│ SELEÇÃO DE DOMICÍLIO BANCÁRIO │
└─────────────────────────────────────────────────────────────┘
PASSO 1 PASSO 2 PASSO 3
┌──────────────┐ ┌──────────────────┐ ┌─��───────────────────┐
│ 600;">GET /banks │──────▶│ 600;">GET /banks/ │─────▶│ Registrar domicílio │
│ │ │ {bank_code}/ │ │ bancário no merchant│
│ Lista todos │ │ not-allowed- │ │ (domínio Merchants) │
│ os bancos │ │ brands │ └─────────────────────┘
│ disponíveis │ │ │
└──────────────┘ │ Verifica se o │
│ banco cobre todas │
│ as bandeiras │
└────────┬─────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
brands: [] (vazio) brands: ["MASTER", "ELO", ...]
│ │
┌──────────┴──────────┐ ┌───────────┴──────────────┐
│ Banco cobre todas │ │ Banco NÃO cobre todas │
│ as bandeiras. │ │ as bandeiras. │
│ Prosseguir com │ │ │
│ banco único. │ │ Indicar um SEGUNDO banco│
└─────────────────────┘ │ apto para as bandeiras │
│ não cobertas. │
└──────────────────────────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
Segundo banco Segundo banco NÃO
informado. informado.
Recebíveis Recebíveis das
garantidos para bandeiras não cobertas
todas as bandeiras. ficam RETIDOS até
regularização.
text
┌─────────────────────────────────────────────────────────────┐
│ SELEÇÃO DE DOMICÍLIO BANCÁRIO │
└─────────────────────────────────────────────────────────────┘
PASSO 1 PASSO 2 PASSO 3
┌──────────────┐ ┌──────────────────┐ ┌─��───────────────────┐
│ 600;">GET /banks │──────▶│ 600;">GET /banks/ │─────▶│ Registrar domicílio │
│ │ │ {bank_code}/ │ │ bancário no merchant│
│ Lista todos │ │ not-allowed- │ │ (domínio Merchants) │
│ os bancos │ │ brands │ └─────────────────────┘
│ disponíveis │ │ │
└──────────────┘ │ Verifica se o │
│ banco cobre todas │
│ as bandeiras │
└────────┬─────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
brands: [] (vazio) brands: ["MASTER", "ELO", ...]
│ │
┌──────────┴──────────┐ ┌───────────┴──────────────┐
│ Banco cobre todas │ │ Banco NÃO cobre todas │
│ as bandeiras. │ │ as bandeiras. │
│ Prosseguir com │ │ │
│ banco único. │ │ Indicar um SEGUNDO banco│
└─────────────────────┘ │ apto para as bandeiras │
│ não cobertas. │
└──────────────────────────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
Segundo banco Segundo banco NÃO
informado. informado.
Recebíveis Recebíveis das
garantidos para bandeiras não cobertas
todas as bandeiras. ficam RETIDOS até
regularização.
Passo a passo
Passo 1 — Listar bancos disponíveis
Chame
GET /v1/banks para obter a lista completa de bancos elegíveis. Filtre e exiba para o usuário apenas os bancos com situation.status = "active". Os campos mais relevantes para exibição são bank_name (nome do banco) e bank_code (código FEBRABAN).Passo 2 — Verificar cobertura de bandeiras
Com o
bank_code do banco escolhido pelo usuário, chame GET /v1/banks/{bank_code}/not-allowed-brands. O retorno indicará se o banco possui alguma restrição de bandeiras.Passo 3 — Registrar o domicílio bancário
Com o banco (ou bancos) selecionados, registre o domicílio bancário do merchant através do domínio Merchants (recurso
MerchantAccount).4. Pré-requisitos
Autenticação
Todos os endpoints exigem um token de acesso obtido previamente via:
text
POST /v1/token
text
POST /v1/token
O token deve ser enviado no header de cada requisição:
text
Authorization: {access_token}
text
Authorization: {access_token}
Não é necessário prefixoBearer. O token é enviado diretamente.
Dependências
| Dependência | Descrição |
|---|---|
| Serviço de Autenticação | O token de acesso deve ser obtido antes de qualquer chamada a este domínio. Consulte a documentação de Autenticação. |
| Domínio Merchants | O domicílio bancário resultante desta seleção é registrado no domínio Merchants. Este serviço apenas auxilia na consulta e validação do banco. |
Perfis e permissões
O acesso a este serviço é restrito a canais e operadores com permissão para realizar credenciamento de merchants na plataforma Getnet.
5. Guia de Integração Rápida
Cenário: selecionar banco e validar cobertura de bandeiras
Etapa 1 — Obter a lista de bancos
text
600;">GET /v1/banks
Authorization: {token}
text
600;">GET /v1/banks
Authorization: {token}
Retorno esperado (parcial):
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"
}
}
]✅ Exiba para o usuário apenas os bancos com
status: "active". Use bank_name para identificação visual e bank_code para as próximas chamadas.Etapa 2 — Verificar bandeiras do banco selecionado
Suponha que o usuário escolheu o 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}
Retorno — banco sem restrições:
json
{
"bank_code": "033",
"bank_name": "",
"brands": []
}json
{
"bank_code": "033",
"bank_name": "",
"brands": []
}✅ O campo
brands está vazio: o banco aceita recebíveis de todas as bandeiras. Prossiga normalmente.Retorno — banco com restrições:
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"
]
}⚠️ O banco não aceita recebíveis de MASTER e AMEX. Neste caso, oriente o usuário a selecionar um segundo banco que cubra essas bandeiras. O segundo banco deve ser validado da mesma forma (Etapa 2) para garantir que cobre as bandeiras em falta.
6. Regras de Negócio
Elegibilidade de bancos
- Somente bancos com
situation.status = "active"estão disponíveis para seleção de domicílio bancário. - Bancos com status
"deactivated"não devem ser exibidos ao usuário nem utilizados no credenciamento.
Bandeiras suportadas pela Getnet
A Getnet opera com quatro bandeiras de adquirência (ADQ):
| Bandeira | Identificação no retorno da API |
|---|---|
| VISA | VISA |
| Mastercard | MASTER |
| Elo | ELO |
| American Express | CARTAO AMEX |
Banco complementar obrigatório
- Quando o banco principal não cobre todas as bandeiras, é necessário indicar um segundo banco para as bandeiras não cobertas.
- O segundo banco deve ser apto a receber das bandeiras específicas que o primeiro não cobre.
- Se o segundo banco não for informado, os recebíveis das bandeiras não cobertas ficarão retidos indefinidamente, até que um banco habilitado seja cadastrado.
Canais com banco próprio
Canais vinculados a bancos já estabelecidos ou cooperativas de crédito que possuam conta corrente própria não devem utilizar este serviço. O domicílio bancário desses canais é predefinido pela própria instituição e informado diretamente no credenciamento.
Campos obrigatórios no schema Bank
| Campo | Obrigatoriedade | Descrição |
|---|---|---|
bank_code | Obrigatório | Código de compensação FEBRABAN do banco. |
bank_country | Obrigatório | País do banco (ISO 3166-1 alpha-2). Atualmente apenas BR. |
7. Tratamento de Erros
| Código HTTP | Significado | O que fazer |
|---|---|---|
400 Bad Request | A requisição foi enviada com parâmetros inválidos ou mal formatados. | Verifique os parâmetros enviados (ex: bank_code com formato inválido, country fora do padrão ISO). |
401 Unauthorized | O token de autenticação está ausente, inválido ou expirado. | Obtenha um novo token via POST /v1/token e reenvie a requisição. |
404 Not Found | O banco informado no caminho da requisição não foi encontrado. | Verifique se o bank_code utilizado foi obtido corretamente via GET /v1/banks e se corresponde a um banco ativo. |
500 Internal Server Error | Erro interno na plataforma Getnet. | Aguarde alguns instantes e tente novamente. Se o problema persistir, acione o suporte Getnet. |
8. Glossário
| Termo | Definição |
|---|---|
| Domicílio bancário | Conta bancária cadastrada pelo merchant para receber os valores das suas vendas. Cada bandeira pode ter um domicílio bancário diferente. |
| Bank code | Código de compensação do banco, controlado pela FEBRABAN no Brasil. É o identificador utilizado para referenciar o banco nas chamadas da API. |
| Bandeira (ADQ) | Rede de pagamento responsável pelo processamento das transações com cartão (ex: VISA, MASTER, ELO, AMEX). Cada bandeira pode ter regras diferentes de liquidação. |
| Banco complementar | Segundo banco indicado pelo merchant para receber os recebíveis de bandeiras que o banco principal não cobre. |
| Status active | Indica que o banco está ativo e disponível para uso como domicílio bancário na Getnet. |
| Status deactivated | Indica que o banco foi desativado e não pode ser utilizado para novos domicílios bancários. |
| Recebíveis retidos | Valores de vendas que não podem ser liquidados por ausência de um banco habilitado para receber da bandeira correspondente. Ficam bloqueados até que um banco apto seja cadastrado. |
| Canal | Parceiro ou instituição que realiza o credenciamento de merchants na plataforma Getnet (ex: banco, cooperativa de crédito, agente comercial). |
| FEBRABAN | Federação Brasileira de Bancos. Organismo responsável pelo registro e atribuição dos códigos de compensação bancária no Brasil. |
| Merchant | Estabelecimento comercial credenciado na Getnet para aceitar pagamentos com cartão. |
On this page
Bancos — Domicílio Bancário