> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Catálogo de bancos

Lista de participantes para o dropdown de TED e de PIX por dados bancários.
Não é a conta credenciada — isso continua em
`GET /v1/accounts/{accountId}/bank-account` (COMPE, agência e número de **quem
você é**).

## Por que um endpoint

TED (`POST .../ted/out`) exige COMPE de 3 dígitos. ISPB de 8 volta
`400 invalid_bank_code`. PIX por dados bancários (`.../pix/out/bank-account`)
prefere ISPB e aceita COMPE no mesmo campo, normalizando.

A UI precisa do par: o usuário escolhe “Itaú” e o integrador manda
`bankCode: "341"` no TED e `bankIspb: "60701190"` no PIX.

`ted` / `pix` importam porque nem todo participante do SPI faz STR, e o
contrário também. Sem flag o dropdown de TED mostra instituição que a API
recusa.

## Listar

`GET /v1/banks` — uma lista só, um participante por linha, os dois códigos
juntos. Exige `Authorization` e `X-Tenant-Id`. Escopo `read`.

```bash
curl -X GET "https://tenant.api.corpx.com/v1/banks" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"
```

```json
{
  "items": [
    {
      "name": "ITAÚ UNIBANCO S.A.",
      "bankCode": "341",
      "ispb": "60701190",
      "ted": true,
      "pix": true
    }
  ]
}
```

Filtre `ted` / `pix` no cliente. Não há paginação.

## Lookup

`GET /v1/banks/{code}` — `341`, `0341` ou `60701190` devolvem a mesma linha.
`404 bank_not_found` se não existir. Formato inválido: `400 invalid_bank_code`.

A lista vem da [relação STR do Banco Central](https://www.bcb.gov.br/content/estabilidadefinanceira/str1/ParticipantesSTR.csv).
O envio de TED/PIX **não** valida contra o catálogo: qualquer COMPE/ISPB
bem-formado continua aceito.