Bancos — Domicilio Bancario
1. Visión General
El servicio de Bancos permite consultar qué instituciones financieras están disponibles para recibir los valores de las transacciones realizadas por los merchants acreditados en Getnet.
Cuando un establecimiento es acreditado, necesita informar una cuenta bancaria donde se depositarán los pagos de sus ventas. Este vínculo se llama domicilio bancario. Este servicio es el punto de partida para esa elección: proporciona la lista de bancos aceptados por Getnet e indica si cada banco es capaz de recibir de todas las marcas de tarjeta con las que opera Getnet.
Sin esta etapa, no es posible garantizar que el merchant recibirá correctamente los valores de todas sus ventas.
2. Contexto y Casos de Uso
Cuándo usar
Este servicio debe ser utilizado durante la jornada de acreditación de un merchant, en la etapa en que el usuario necesita seleccionar el banco en el que desea recibir sus pagos.
⚠️ Importante: Canales vinculados a bancos ya establecidos o a cooperativas de crédito que posean cuenta corriente propia no utilizan este servicio. En estos casos, la cuenta bancaria ya es conocida y predefinida por el propio canal, siendo informada directamente en la acreditación sin necesidad de consulta.
Escenarios de uso
| Escenario | Descripción |
|---|---|
| Acreditación de nuevo merchant | El operador necesita mostrar al usuario la lista de bancos disponibles para elegir el domicilio bancario. |
| Validación de cobertura de marcas | Tras elegir el banco, verificar si acepta recibos de todas las marcas (VISA, MASTER, ELO, AMEX). |
| Indicación de banco complementario | Cuando el banco elegido no cubre todas las marcas, orientar al usuario a indicar un segundo banco para las marcas restantes. |
3. Flujo Principal
El servicio está compuesto por dos endpoints que deben ser utilizados en secuencia durante la acreditación:
text
┌─────────────────────────────────────────────────────────────┐
│ SELECCIÓN DE DOMICILIO BANCARIO │
└─────────────────────────────────────────────────────────────┘
PASO 1 PASO 2 PASO 3
┌──────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ 600;">GET /banks │──────▶│ 600;">GET /banks/ │─────▶│ Registrar domicilio │
│ │ │ {bank_code}/ │ │ bancario en merchant│
│ Lista todos │ │ not-allowed- │ │ (dominio Merchants) │
│ los bancos │ │ brands │ └────���────────────────┘
│ disponibles │ │ │
└──────────────┘ │ Verifica si el │
│ banco cubre todas│
│ las marcas │
└────────┬─────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
brands: [] (vacío) brands: ["MASTER", "ELO", ...]
│ │
┌──────────┴──────────┐ ┌───────────┴──────────────┐
│ Banco cubre todas │ │ Banco NO cubre todas │
│ las marcas. │ │ las marcas. │
│ Continuar con │ │ │
│ banco único. │ │ Indicar un SEGUNDO │
└─────────────────────┘ │ banco apto para las │
│ marcas no cubiertas. │
└─────────────────────────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
Segundo banco Segundo banco NO
informado. informado.
Recibos garantizados Recibos de las
para todas las marcas. marcas no cubiertas
quedan RETENIDOS hasta
regularización.
text
┌─────────────────────────────────────────────────────────────┐
│ SELECCIÓN DE DOMICILIO BANCARIO │
└─────────────────────────────────────────────────────────────┘
PASO 1 PASO 2 PASO 3
┌──────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ 600;">GET /banks │──────▶│ 600;">GET /banks/ │─────▶│ Registrar domicilio │
│ │ │ {bank_code}/ │ │ bancario en merchant│
│ Lista todos │ │ not-allowed- │ │ (dominio Merchants) │
│ los bancos │ │ brands │ └────���────────────────┘
│ disponibles │ │ │
└──────────────┘ │ Verifica si el │
│ banco cubre todas│
│ las marcas │
└────────┬─────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
brands: [] (vacío) brands: ["MASTER", "ELO", ...]
│ │
┌──────────┴──────────┐ ┌───────────┴──────────────┐
│ Banco cubre todas │ │ Banco NO cubre todas │
│ las marcas. │ │ las marcas. │
│ Continuar con │ │ │
│ banco único. │ │ Indicar un SEGUNDO │
└─────────────────────┘ │ banco apto para las │
│ marcas no cubiertas. │
└─────────────────────────┘
│
┌────────────┴────────────┐
│ │
▼ ▼
Segundo banco Segundo banco NO
informado. informado.
Recibos garantizados Recibos de las
para todas las marcas. marcas no cubiertas
quedan RETENIDOS hasta
regularización.
Paso a paso
Paso 1 — Listar bancos disponibles
Llama a
GET /v1/banks para obtener la lista completa de bancos elegibles. Filtra y muestra al usuario solo los bancos con situation.status = "active". Los campos más relevantes para mostrar son bank_name (nombre del banco) y bank_code (código FEBRABAN).Paso 2 — Verificar cobertura de marcas
Con el
bank_code del banco elegido por el usuario, llama a GET /v1/banks/{bank_code}/not-allowed-brands. El retorno indicará si el banco tiene alguna restricción de marcas.Paso 3 — Registrar el domicilio bancario
Con el(los) banco(s) seleccionados, registra el domicilio bancario del merchant a través del dominio Merchants (recurso
MerchantAccount).4. Prerrequisitos
Autenticación
Todos los endpoints requieren un token de acceso obtenido previamente vía:
text
POST /v1/token
text
POST /v1/token
El token debe enviarse en el header de cada solicitud:
text
Authorization: {access_token}
text
Authorization: {access_token}
No es necesario el prefijoBearer. El token se envía directamente.
Dependencias
| Dependencia | Descripción |
|---|---|
| Servicio de Autenticación | El token de acceso debe obtenerse antes de cualquier llamada a este dominio. Consulta la documentación de Autenticación. |
| Dominio Merchants | El domicilio bancario resultante de esta selección se registra en el dominio Merchants. Este servicio solo ayuda en la consulta y validación del banco. |
Perfiles y permisos
El acceso a este servicio está restringido a canales y operadores con permiso para acreditar merchants en la plataforma Getnet.
5. Guía Rápida de Integración
Escenario: seleccionar banco y validar cobertura de marcas
Etapa 1 — Obtener la 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"
}
}
]✅ Muestra al usuario solo los bancos con
status: "active". Usa bank_name para identificación visual y bank_code para las próximas llamadas.Etapa 2 — Verificar marcas del banco seleccionado
Supón que el usuario eligió 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 sin restricciones:
json
{
"bank_code": "033",
"bank_name": "",
"brands": []
}json
{
"bank_code": "033",
"bank_name": "",
"brands": []
}✅ El campo
brands está vacío: el banco acepta recibos de todas las marcas. Continúa normalmente.Retorno — banco con restricciones:
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"
]
}⚠️ El banco no acepta recibos de MASTER y AMEX. En este caso, orienta al usuario a seleccionar un segundo banco que cubra esas marcas. El segundo banco debe ser validado de la misma forma (Etapa 2) para garantizar que cubre las marcas faltantes.
6. Reglas de Negocio
Elegibilidad de bancos
- Solo los bancos con
situation.status = "active"están disponibles para la selección de domicilio bancario. - Los bancos con status
"deactivated"no deben mostrarse al usuario ni utilizarse en la acreditación.
Marcas soportadas por Getnet
Getnet opera con cuatro marcas de adquirencia (ADQ):
| Marca | Identificación en el retorno de la API |
|---|---|
| VISA | VISA |
| Mastercard | MASTER |
| Elo | ELO |
| American Express | CARTAO AMEX |
Banco complementario obligatorio
- Cuando el banco principal no cubre todas las marcas, es necesario indicar un segundo banco para las marcas no cubiertas.
- El segundo banco debe ser apto para recibir de las marcas específicas que el primero no cubre.
- Si el segundo banco no es informado, los recibos de las marcas no cubiertas quedarán retenidos indefinidamente, hasta que se registre un banco habilitado.
Canales con banco propio
Los canales vinculados a bancos ya establecidos o cooperativas de crédito que posean cuenta corriente propia no deben utilizar este servicio. El domicilio bancario de esos canales es predefinido por la propia institución e informado directamente en la acreditación.
Campos obligatorios en el schema Bank
| Campo | Obligatoriedad | Descripción |
|---|---|---|
bank_code | Obligatorio | Código de compensación FEBRABAN del banco. |
bank_country | Obligatorio | País del banco (ISO 3166-1 alpha-2). Actualmente solo BR. |
7. Tratamiento de Errores
| Código HTTP | Significado | Qué hacer |
|---|---|---|
400 Bad Request | La solicitud fue enviada con parámetros inválidos o mal formateados. | Verifique los parámetros enviados (ej: bank_code con formato inválido, country fuera del estándar ISO). |
401 Unauthorized | El token de autenticación está ausente, inválido o expirado. | Obtenga un nuevo token vía POST /v1/token y reenvíe la solicitud. |
404 Not Found | El banco informado en la ruta de la solicitud no fue encontrado. | Verifique si el bank_code utilizado fue obtenido correctamente vía GET /v1/banks y si corresponde a un banco activo. |
500 Internal Server Error | Error interno en la plataforma Getnet. | Espere algunos instantes e intente nuevamente. Si el problema persiste, contacte al soporte Getnet. |
8. Glosario
| Término | Definición |
|---|---|
| Domicilio bancario | Cuenta bancaria registrada por el merchant para recibir los valores de sus ventas. Cada marca puede tener un domicilio bancario diferente. |
| Bank code | Código de compensación del banco, controlado por FEBRABAN en Brasil. Es el identificador utilizado para referenciar el banco en las llamadas de la API. |
| Marca (ADQ) | Red de pago responsable del procesamiento de las transacciones con tarjeta (ej: VISA, MASTER, ELO, AMEX). Cada marca puede tener reglas diferentes de liquidación. |
| Banco complementario | Segundo banco indicado por el merchant para recibir los recibos de marcas que el banco principal no cubre. |
| Status active | Indica que el banco está activo y disponible para uso como domicilio bancario en Getnet. |
| Status deactivated | Indica que el banco fue desactivado y no puede ser utilizado para nuevos domicilios bancarios. |
| Recibos retenidos | Valores de ventas que no pueden ser liquidados por ausencia de un banco habilitado para recibir de la marca correspondiente. Quedan bloqueados hasta que se registre un banco apto. |
| Canal | Socio o institución que realiza la acreditación de merchants en la plataforma Getnet (ej: banco, cooperativa de crédito, agente comercial). |
| FEBRABAN | Federación Brasileña de Bancos. Organismo responsable del registro y atribución de los códigos de compensación bancaria en Brasil. |
| Merchant | Establecimiento comercial acreditado en Getnet para aceptar pagos con tarjeta. |
En esta página
Bancos — Domicilio Bancario