> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Banks

> The banks a merchant's customer can pay from, for a country and a currency

`GET /merchants/{id}/banks` lists the banks a payment transaction to the merchant could be paid from, for a customer in `country` paying in `currency`. They're the banks Quidkey's checkout offers that customer, so you can show them on your own page, such as bank buttons. Send the one the customer chooses as `authorization.bank` when you [create the payment transaction](https://docs.quidkey.com/api-v1/journeys/hosted-checkout.md#open-checkout-at-the-customers-bank), and the checkout opens with it chosen.

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/banks?country=GB&currency=GBP' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

```json Response theme={null}
{
  "result": [
    {
      "_type": "bank",
      "_uri": "/banks/38c39d03-8df3-4980-b0a8-7e283c8c62dd",
      "_view": "full",
      "id": "38c39d03-8df3-4980-b0a8-7e283c8c62dd",
      "name": "Monzo Bank",
      "logo_url": "https://cdn.example/monzo.png",
      "country": "GB",
      "created_at": "2026-01-02T03:04:05.678Z",
      "updated_at": "2026-02-03T04:05:06.789Z"
    }
  ],
  "entities": {},
  "not_included": [],
  "pagination": { "type": "cursor", "limit": 25, "next_cursor": "c2Vjb25k", "has_more": true }
}
```

| Parameter | Meaning |
| - | - |
| `country` | Required. The customer's country, ISO 3166-1 alpha-2, as `customer_details.country` on a payment transaction. |
| `currency` | Required. The payment transaction's currency, ISO 4217. |
| `is_test` | `true` lists the banks of a [test payment transaction](https://docs.quidkey.com/api-v1/journeys/test-payments.md). Without it the list is a live payment transaction's. |
| `q` | Only banks whose name holds this, ignoring case. |

The list pages as every list does, with `limit` and `cursor`. See [Lists, pagination and filters](https://docs.quidkey.com/api-v1/standards/collections.md).

## Order

The country's popular banks come first, in the order Quidkey curates for it, then every other bank by name. The order is the same for every customer and every request, so a cursor carries on where the last page ended.

The banks follow the merchant's route for that country and currency, so two merchants can see different lists for the same customer. A test payment transaction's route can offer banks a live one doesn't.

## Refusals

A route a payment transaction can't take is refused with the code that creating a payment transaction gives. Listing a live route's banks doesn't need the merchant to take live payment transactions.

| Refusal | Meaning |
| - | - |
| 409 `MERCHANT_CANNOT_TAKE_PAYMENT` | The merchant can't take a payment transaction in this currency from a customer in this country. |
| 422 `BANK_SELECTION_NOT_SUPPORTED` | The payment transaction is taken on its provider's own page, where the customer doesn't choose a bank. A live AUD payment transaction from Australia is taken this way, by PayTo. |
| 400 `CURRENCY_COUNTRY_MISMATCH` | This currency can't be taken from a customer in this country. |
| 400 `CUSTOMER_COUNTRY_NOT_SUPPORTED` | Quidkey doesn't take payment transactions from a customer in this country. |
| 400 `CURRENCY_NOT_SUPPORTED` | This currency isn't supported. |

## Reading One Bank

`GET /banks/{id}` reads one bank, which is what each entry's `_uri` names. It's reference data, read with `banks:get`. A bank Quidkey doesn't offer answers 404.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.