> ## 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.

# List a merchant's banks

> Lists the banks a payment transaction to this merchant could be paid from, for a customer in `country` paying in `currency`: the banks Quidkey's checkout offers that customer. The route's popular banks come first, in Quidkey's curated order, then the rest by name. The order is the same for every customer. Listing a live route's banks doesn't need the merchant to take live payment transactions. `BANK_SELECTION_NOT_SUPPORTED` means the payment transaction's provider takes it on its own page, where the customer doesn't choose a bank.

Credentials: `partner`, `merchant`

Permission: `banks:list`



## OpenAPI

````yaml /api-reference/v1/openapi.json get /merchants/{id}/banks
openapi: 3.1.0
info:
  title: Quidkey API
  version: 1.0.0
  description: >-
    The Quidkey public API.


    Within a version, a response can carry what this document doesn't list yet:
    a new field, a new value of an enum, a new error code. Handle a value you
    don't recognise rather than refusing the response. A client generated from
    this document turns an `enum` into a closed type unless told otherwise, so
    turn on its option for unknown values, such as openapi-generator's
    `enumUnknownDefaultCase`. A request is held to what's listed: a value it
    doesn't list is refused.
  contact:
    name: Quidkey
    url: https://docs.quidkey.com
servers:
  - url: https://api.quidkey.com/v1
security:
  - bearer: []
tags:
  - name: account_owner
  - name: agreement
  - name: agreement_acceptance
  - name: api_key
  - name: bank
  - name: bank_account
  - name: capability
  - name: country
  - name: identity_verification
  - name: legal_entity
  - name: merchant
  - name: party
  - name: payment_link
  - name: payout
  - name: transaction
  - name: webhook_endpoint
paths:
  /merchants/{id}/banks:
    get:
      tags:
        - bank
      summary: List a merchant's banks
      description: >-
        Lists the banks a payment transaction to this merchant could be paid
        from, for a customer in `country` paying in `currency`: the banks
        Quidkey's checkout offers that customer. The route's popular banks come
        first, in Quidkey's curated order, then the rest by name. The order is
        the same for every customer. Listing a live route's banks doesn't need
        the merchant to take live payment transactions.
        `BANK_SELECTION_NOT_SUPPORTED` means the payment transaction's provider
        takes it on its own page, where the customer doesn't choose a bank.


        Credentials: `partner`, `merchant`


        Permission: `banks:list`
      operationId: bank.list
      parameters:
        - name: id
          in: path
          required: true
          schema:
            minLength: 1
            type: string
        - name: country
          in: query
          required: true
          description: The customer's country, ISO 3166-1 alpha-2.
          schema:
            pattern: ^[A-Z]{2}$
            type: string
        - name: currency
          in: query
          required: true
          description: The payment transaction's currency, ISO 4217.
          schema:
            pattern: ^[A-Z]{3}$
            type: string
        - name: cursor
          in: query
          required: false
          description: >-
            An opaque cursor from `next_cursor`, valid with the filters it was
            issued for.
          schema:
            minLength: 1
            maxLength: 1024
            type: string
        - name: is_test
          in: query
          required: false
          description: Lists the banks of a test payment transaction instead of a live one.
          schema:
            default: false
            type: boolean
        - name: limit
          in: query
          required: false
          description: The page size.
          schema:
            minimum: 1
            maximum: 100
            default: 25
            type: integer
        - name: q
          in: query
          required: false
          description: Only banks whose name holds this, ignoring case.
          schema:
            minLength: 1
            maxLength: 100
            type: string
      responses:
        '200':
          description: A list of bank, in the full view.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                required:
                  - result
                  - entities
                  - not_included
                  - pagination
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/BankFull'
                  entities:
                    additionalProperties: false
                    description: Nothing can be included here.
                    type: object
                    properties: {}
                  not_included:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotIncludedEntry'
                  pagination:
                    $ref: '#/components/schemas/CursorPagination'
        '400':
          description: >-
            `CURRENCY_COUNTRY_MISMATCH`: This currency can't be used for a
            customer in this country.


            `CURRENCY_NOT_SUPPORTED`: This currency isn't supported.


            `CUSTOMER_COUNTRY_NOT_SUPPORTED`: Payment transactions from this
            customer's country aren't accepted.


            `VALIDATION_FAILED`: The request is malformed or failed validation.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - CURRENCY_COUNTRY_MISMATCH
            - CURRENCY_NOT_SUPPORTED
            - CUSTOMER_COUNTRY_NOT_SUPPORTED
            - VALIDATION_FAILED
        '401':
          description: '`UNAUTHENTICATED`: A valid bearer token is required.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - UNAUTHENTICATED
        '403':
          description: >-
            `FORBIDDEN`: This credential doesn't have permission for this
            endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - FORBIDDEN
        '404':
          description: '`NOT_FOUND`: Not found.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_FOUND
        '406':
          description: '`NOT_ACCEPTABLE`: This endpoint doesn''t offer the format in Accept.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_ACCEPTABLE
        '409':
          description: >-
            `MERCHANT_CANNOT_TAKE_PAYMENT`: This merchant can't take a payment
            transaction in this currency from a customer in this country.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - MERCHANT_CANNOT_TAKE_PAYMENT
        '422':
          description: >-
            `BANK_SELECTION_NOT_SUPPORTED`: A payment transaction in this
            currency from a customer in this country is paid on its provider's
            own page, with no choice of bank.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - BANK_SELECTION_NOT_SUPPORTED
        '429':
          description: '`RATE_LIMITED`: Too many requests.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - RATE_LIMITED
        '500':
          description: '`INTERNAL_ERROR`: Something went wrong on our side.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - INTERNAL_ERROR
        '503':
          description: '`SERVICE_UNAVAILABLE`: The service is busy. Try again shortly.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - SERVICE_UNAVAILABLE
components:
  headers:
    RequestId:
      description: Identifies this request. Quote it to support.
      schema:
        type: string
    RetryAfter:
      description: How many seconds to wait before retrying.
      schema:
        minimum: 0
        type: integer
  schemas:
    BankFull:
      additionalProperties: false
      type: object
      required:
        - _type
        - _uri
        - _view
        - id
        - created_at
        - updated_at
        - name
        - logo_url
        - country
      properties:
        _type:
          const: bank
          type: string
        _uri:
          pattern: ^/
          description: The canonical URI, relative to the version root.
          type: string
        _view:
          const: full
          type: string
        id:
          type: string
        created_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        updated_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        name:
          type: string
        logo_url:
          anyOf:
            - format: uri
              pattern: ^https://
              maxLength: 2048
              type: string
            - type: 'null'
          description: '`null` where Quidkey holds no logo for the bank.'
        country:
          pattern: ^[A-Z]{2}$
          type: string
          description: The bank's country, ISO 3166-1 alpha-2.
    NotIncludedEntry:
      additionalProperties: false
      type: object
      required:
        - link
        - reason
      properties:
        link:
          $ref: '#/components/schemas/AnyLink'
        reason:
          type: string
          enum:
            - no_permission
            - not_published
          description: >-
            Why this link has no entity.


            - `no_permission`: This credential can't read it. Fetching it
            answers 403, or 404 where a 403 would reveal that it exists.

            - `not_published`: The API doesn't show it: a type it doesn't
            publish, or a record it doesn't show on a type it does, such as a
            failed payout. Fetching it, where it has a URI, answers 404.
    CursorPagination:
      additionalProperties: false
      type: object
      required:
        - type
        - limit
        - next_cursor
        - has_more
      properties:
        type:
          const: cursor
          type: string
        limit:
          minimum: 1
          maximum: 100
          type: integer
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
        has_more:
          type: boolean
    Error:
      additionalProperties: false
      type: object
      required:
        - error
      properties:
        error:
          additionalProperties: false
          type: object
          required:
            - code
            - message
            - details
            - retryable
            - request_id
          properties:
            code:
              description: Branch on this. New codes can appear.
              type: string
            message:
              description: For people. It can change.
              type: string
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
            retryable:
              description: >-
                Whether sending the same request again unchanged, after a wait,
                can succeed with nothing else changing.
              type: boolean
            request_id:
              description: Quote this to support.
              type: string
    AnyLink:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - _link
            - _type
            - id
          properties:
            _link:
              pattern: ^/
              type: string
            _type:
              type: string
            id:
              type: string
        - additionalProperties: false
          type: object
          required:
            - _type
            - id
          properties:
            _type:
              type: string
            id:
              type: string
      x-link-target:
        resource: any
        kind: any
        is_published: true
    ErrorDetail:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - field
            - message
          properties:
            field:
              type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - required_actions
            - message
          properties:
            required_actions:
              description: The `required_actions` codes holding this back.
              type: array
              items:
                type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - available_percent
            - message
          properties:
            available_percent:
              $ref: '#/components/schemas/Percent'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - current_agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            current_agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - legal_entity
            - message
          properties:
            legal_entity:
              $ref: '#/components/schemas/LegalEntityLink'
            message:
              type: string
    Percent:
      pattern: ^\d+(\.\d+)?$
      description: 'A percentage as a decimal string: `"25.00"` is 25%.'
      type: string
    AgreementLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: agreement
          type: string
        id:
          type: string
      x-link-target:
        resource: agreement
        kind: resource
        is_published: true
        views:
          - full
    LegalEntityLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: legal_entity
          type: string
        id:
          type: string
      x-link-target:
        resource: legal_entity
        kind: resource
        is_published: true
        views:
          - full
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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