---
description: >-
  Look up a bank by its code and country using GET /bank, or list all banks
  in a country with pagination using GET /bank/list.
---

# Banks

The Banks API provides two endpoints for querying bank information: a direct lookup by bank code and a paginated listing by country. Use these to populate bank selection dropdowns and validate bank codes before submitting payments.

---

## Look Up a Bank

Retrieve details for a specific bank by its code and country.

### Endpoint

```
GET https://{FQDN}/bank
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Query Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `bankNumber` | string | ✅ | Bank institution code (e.g., `"341"`, `"7339"`) |
| `countryCode` | string | ✅ | Country code (e.g., `"BR"`, `"SG"`) |

### Example Request

```bash
curl -X GET 'https://{FQDN}/bank?bankNumber=341&countryCode=BR' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "bankCode": "341",
  "bankName": "Itaú Unibanco",
  "countryCode": "BR",
  "swift": "ITAUBRSP"
}
```

---

## List Banks by Country

Retrieve a paginated list of all banks available in a given country.

### Endpoint

```
GET https://{FQDN}/bank/list
```

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Query Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | ✅ | Country code (e.g., `"BR"`, `"US"`, `"SG"`) |
| `page` | integer | ❌ | Page number (zero-based) |
| `resultsPerPage` | integer | ❌ | Number of results per page |

### Example Request

```bash
curl -X GET 'https://{FQDN}/bank/list?countryCode=BR&page=0&resultsPerPage=5' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
```

### Response (200)

```json
{
  "banks": [
    {
      "bankCode": "001",
      "bankName": "Banco do Brasil",
      "countryCode": "BR",
      "swift": "BRASBRRJ"
    },
    {
      "bankCode": "033",
      "bankName": "Banco Santander",
      "countryCode": "BR",
      "swift": "BSCHBRSP"
    },
    {
      "bankCode": "104",
      "bankName": "Caixa Econômica Federal",
      "countryCode": "BR",
      "swift": "CABORJBR"
    },
    {
      "bankCode": "237",
      "bankName": "Banco Bradesco",
      "countryCode": "BR",
      "swift": "BBDEBRSP"
    },
    {
      "bankCode": "341",
      "bankName": "Itaú Unibanco",
      "countryCode": "BR",
      "swift": "ITAUBRSP"
    }
  ],
  "page": 0,
  "resultsPerPage": 5,
  "totalResults": 42
}
```

## What's Next

- [Schemas](schemas.md) — Get country-specific field requirements for accounts, payouts, and persons
- [Push Transaction](../payment/push-transaction.md) — Send payouts to bank accounts, cards, PIX, and wallets
- [Alias Directory](../payment/alias-directory.md) — Resolve instant payment aliases before sending payouts