# Get banks v2

The GET /v2/banks endpoint retrieves a list of connected banks matching the parameters specified.

Endpoint: GET /v2/banks
Security: Bearer, BasicAuth

## Query parameters:

  - `page` (integer)
    The index of the page currently being retrieved.

  - `perPage` (integer)
    The number of records per page.
    Example: 10

  - `sort` (string)
    The key to sort the result. This can be NAME (Bank's name), STANDARD (OpenBankingStandard), RANK, or COUNTRY.
    Enum: "COUNTRY", "STANDARD", "RANK", "NAME"

  - `memberId` (string)
    The Token.io-assigned member id of the TPP.

  - `tppId` (string)
    Filters for banks for which the TPP represented by this tppId has access.

  - `ids` (array)
    Filters for banks with a bankId (case-insensitive) matching any of the ids listed, up to a maximum of 1000. Only exact (full string) matches are returned.

  - `search` (string)
    Filters for banks with a name or identifiers containing this search string.
    Example: "hsbc"

  - `bankGroup` (string)
    Filters for banks that are members of the bank group specified.
    Example: ["HSBC","Coop"]

  - `bankSubGroup` (string)
    Filters for banks that are part of the bank sub-group specified.
    Example: ["CMM Grand","Banque Populaire","La Banque"]

  - `bankCode` (string)
    Filters for banks with a BIC (or BLZ, if German) that matches this bankCode. The BIC must have a string length of 8 or 11. The BLZ must have a string length of 8.

  - `openBankingStandards` (array)
    Filters for banks that are accessed through any of the listed standards.
    Enum: "UK_Open_Banking_Standard", "Starling_Bank_API", "PolishAPI", "STET_PSD2_API", "Citi_Handlowy_PSD2_API", "NextGenPSD2", "Slovak_Banking_API_Standard", "Czech_Open_Banking_Standard", "American_Express_PSD2_API", "Budapest_Bank_API", "Token"

  - `countries` (array)
    Filters for banks that are located in the countries specified by this list of two-letter country code in upper case (ISO 3166-1 alpha-2).

  - `bics` (array)
    Filters for banks whose BIC matches any of the listed BICs (case-insensitive), up to a maximum of 1000.
    Example: ["BKENGB2L"]

  - `supportedLocalInstruments` (array)
    Filters for banks that support any of the listed payment networks.
    Example: ["SEPA","SEPA_INSTANT","FASTER_PAYMENTS"]

  - `supportsAccountList` (boolean)
    Filters for banks that support fetching accounts.

  - `supportsAccountDetails` (boolean)
    Filters for banks that support fetching account details.

  - `supportsAccountBalance` (boolean)
    Filters for banks that support fetching account balances.

  - `supportsTransactionList` (boolean)
    Filters for banks that support fetching transactions.

  - `supportsTransactionDetails` (boolean)
    Filters for banks that support fetching transaction details.

  - `supportsStandingOrderList` (boolean)
    Filters for banks that support the fetching standing orders.

  - `supportsTransactionsDateFilter` (boolean)
    Filters for banks that support feting transactions using a date filter.

  - `requiresOneStepPayment` (boolean)
    Filters for banks that only support immediate redemption of transfers.

  - `supportsSinglePayment` (boolean)
    Filters for banks that support single immediate payments.
    Example: true

  - `supportsScheduledPayment` (boolean)
    Filters for banks that support future dated scheduled payments.

  - `supportsStandingOrder` (boolean)
    Filters for banks that support recurring payments/standing orders.

  - `supportsReturnRefundAccount` (boolean)
    Filters for the banks that support request of refund account.

  - `supportsReturnRefundAccountHolderName` (boolean)
    Filters for banks that support returning the refund account holder name.

  - `supportsFundsConfirmation` (boolean)
    Filters for the banks that support confirmation of available funds.

  - `supportsVariableRecurringPayment` (boolean)
    Filters for banks that support variable recurring payments.

## Response 200 fields (application/json):

  - `banks` (array)
    This field contains information for each bank matching the request criteria.

  - `banks.id` (string)
    The Token.io bank identifier.
    Example: "ob-modelo"

  - `banks.bic` (string)
    The Business Identifier Code (BIC), ISO 9362, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long."
    Example: "BOFIIE2D"

  - `banks.name` (string)
    The commonly recognised name of the bank.
    Example: "GoldBank"

  - `banks.logoUri` (string)
    The URI of the location of the square bank avatar icon.
    Example: "https://example.com/path/full.png"

  - `banks.bankGroup` (string)
    The name of the banking group in which this bank holds membership.
    Example: "XYZ-Bank-Group"

  - `banks.bankSubGroup` (string)
    The name of the sub-banking group in which this bank holds membership.
    Example: "Sub-XYZ-Bank-Group"

  - `banks.countries` (array)
    A list of two-letter country code in upper case (ISO 3166-1 alpha-2), in which this bank operates.
    Example: ["DE","IT"]

  - `banks.openBankingStandard` (string)
    Specifies the API standard adopted by the bank.
    Enum: "Invalid_Standard", "UK_Open_Banking_Standard", "Starling_Bank_API", "PolishApi", "STET_PSD2_API", "Citi_Handlowy_PSD2_API", "NextGenPsd2", "Slovak_Banking_API_Standard", "Czech_Open_Banking_Standard", "American_Express_PSD2_API", "Budapest_Bank_API"

  - `banks.initialEmbeddedAuthFields` (object)
    Contains information used in embedded authentication flows. These are optional credential request fields.

  - `banks.initialEmbeddedAuthFields.type` (string, required)
    The type determines how the field is presented to the user. FIELD - displays a form with a text input field; use displayName value to add a label.PASSWORD - displays a form with a password input field; use displayName value to add a label.CHOICE_FIELD - displays a form that allows the user to choose one of the provided options; use displayName value to add a label.
    Enum: "FIELD", "PASSWORD", "CHOICE_FIELD"

  - `banks.initialEmbeddedAuthFields.id` (string, required)
    The ID used when passing the value of this field to Token.io.
    Example: "67891234"

  - `banks.initialEmbeddedAuthFields.displayName` (string, required)
    The name of the requested field displayed to the user.
    Example: "Password:"

  - `banks.initialEmbeddedAuthFields.additionalInformation` (string)
    Additional information about this field.
    Example: "This field is required."

  - `banks.initialEmbeddedAuthFields.options` (array)
    A list of options for the user to select from. For example, it can be an SCA method choice (SMS message, phone call etc.), or confirm/decline options for a confirmation page. The customer sends one of the values back to Token.io with the corresponding id.

  - `banks.mandatoryFields` (array)
    Contains the fields required by the bank, which the TPP must populate in the token request, where applicable.

  - `banks.mandatoryFields.products` (array)
    The products this mandatory fields entry applies to.
    Example: ["SIP"]

  - `banks.mandatoryFields.fieldPaths` (array)
    The paths to the mandatory fields for this entry.
    Example: ["initiation.debtor"]

  - `banks.mandatoryFields.paymentTypes` (array)
    The types of payments (International/Domestic) this mandatory fields entry applies to.
    Example: ["International"]

  - `banks.mandatoryFields.localInstruments` (array)
    The local instruments this mandatory fields entry applies to.
    Example: ["SEPA"]

  - `banks.maintenanceWindow` (array)
    Details of the bank's planned or unplanned maintenance window.

  - `banks.maintenanceWindow.startTime` (string)
    The start time of the maintenance window (in ISO 8601 format).
    Example: "2023-05-03T12:28:20.466Z"

  - `banks.maintenanceWindow.endTime` (string)
    The end time of the maintenance window (in ISO 8601 format).
    Example: "2023-05-03T12:40:25.47Z"

  - `banks.maintenanceWindow.type` (string)
    The bank status:NO_DOWNTIME_EXPECTED - the bank is currently connected, accepting API calls, and returning appropriate responsesDOWNTIME_EXPECTED - there is a planned outage between the startTime and endTime specifiedOUTAGE - connection interrupted; the bank cannot currently accept API calls for this service between the startTime and endTime specified
    Enum: "INVALID", "NO_DOWNTIME_EXPECTED", "DOWNTIME_EXPECTED", "OUTAGE"

  - `banks.maintenanceWindow.productType` (string)
    The bank product:AIS - Account Information ServicesSIP - all payment services including Single Immediate Payments, Future Dated Payments, Standing Orders
    Enum: "INVALID", "AIS", "SIP"

  - `banks.scaMethods` (array)
    Enum: "INVALID_SCA_METHOD", "REDIRECT", "DECOUPLED", "CONFIRMATION_PAGE", "MULTI_REDIRECT", "EMBEDDED_SINGLE_STEP", "EMBEDDED_MULTI_STEP"

  - `banks.fieldsFormatInformation` (array)
    Contains bank-dependent formatting constraints indicating allowable characters, if any.

  - `banks.fieldsFormatInformation.constraint` (string)
    The regex specifying allowed characters. See https://regexr.com/3cr6fhttps://regexr.com/3cr6f for more details.
    Example: "^[A-Za-z0-9?:()./,'+\\-\\s]*$"

  - `banks.fieldsFormatInformation.v2Name` (string)
    The name of the field in the Token.io requestpayload with bank-imposed formatting constraints.
    Example: "description"

  - `banks.fieldsFormatInformation.v2Path` (string)
    The object.field path indicating the constrained field's position in the Token.io requestPayload.
    Example: "credentials.credentials1"

  - `banks.supportedLocalInstruments` (array)
    Payment methods/rails supported by the bank.
    Example: ["SEPA","SEPA_INSTANT","FASTER_PAYMENTS"]

  - `banks.operationalTime` (string)
    Specifies the bank’s days and hours of operation in a normal week. Does not take into account bank-specific public holidays, which may or may not be considered out-of-operation time.
    Example: "MON to FRI, 00:00 to 24:00 GMT+1"

  - `banks.transactionHistoryLimit` (integer)
    Defines the number of transaction history records allowed per page, -1 (unlimited) or a positive integer (record limit).
    Example: 65

  - `banks.supportsAccountList` (boolean)
    The bank connection supports fetching accounts.
    Example: true

  - `banks.supportsAccountDetails` (boolean)
    The bank connection supports fetching account details.
    Example: true

  - `banks.supportsAccountBalance` (boolean)
    The bank connection supports fetching account balances.
    Example: true

  - `banks.supportsTransactionList` (boolean)
    The bank connection supports fetching transactions.
    Example: true

  - `banks.supportsTransactionDetails` (boolean)
    The bank connection supports fetching transaction details.
    Example: true

  - `banks.supportsStandingOrderList` (boolean)
    The bank connection supports the fetching standing orders.
    Example: true

  - `banks.supportsTransactionsDateFilter` (boolean)
    The bank connection supports feting transactions using a date filter.
    Example: true

  - `banks.requiresOneStepPayment` (boolean)
    The bank connection only supports immediate redemption of transfers.
    Example: true

  - `banks.supportsSinglePayment` (boolean)
    The bank connection supports single immediate payments.
    Example: true

  - `banks.supportsScheduledPayment` (boolean)
    The bank connection supports future dated scheduled payments.
    Example: true

  - `banks.supportsSendPayment` (boolean)
    The bank connection supports payment initiation.

  - `banks.supportsReceivePayment` (boolean)
    The bank connection supports the receipt of payments.

  - `banks.supportsStandingOrder` (boolean)
    The bank connection supports recurring payments/standing orders.
    Example: true

  - `banks.supportsReturnRefundAccount` (boolean)
    The bank connection supports requesting of refund accounts.
    Example: true

  - `banks.supportsFundsConfirmation` (boolean)
    The bank connection supports confirmation of available funds.
    Example: true

  - `banks.supportsVariableRecurringPayment` (boolean)
    The bank connection supports variable recurring payments.
    Example: true

  - `paging` (object)
    Contains the page information for response content.

  - `paging.page` (integer)
    The index of the current page.
    Example: 15

  - `paging.pageCount` (integer)
    The number of records per page.
    Example: 80

  - `paging.perPage` (integer)
    The number of total pages.
    Example: 32

  - `paging.totalCount` (integer)
    The number of total records.
    Example: 2500

  - `rank` (integer)
    Sorts banks by rank.
    Example: [1,2,100]

  - `bankSubGroup` (string)
    Filters for banks that are part of the bank sub-group specified.
    Example: ["CMM Grand","Banque Populaire","La Banque"]

## Response 400 fields (application/json):

  - `error` (any, required)

## Response 401 fields (application/json):

  - `error` (object)
    The request does not have valid authentication credentials needed to perform the operation.

  - `error.message` (string)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 403 fields (application/json):

  - `error` (object, required)
    The error returned when the member is not authorized to perform the given operation: PermissionDenied. This error message will be accompanied by the reason from the bank. Typically this means the access token has expired and the user must re-authenticate with the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 500 fields (application/json):

  - `error` (object)
    This could refer to either an error by the payment service provider or the bank. When the bank reports a 5xx error, "token-external-error": "true" is set as a header in the HTTP response, indicating that the "internal" error originates from the bank. When one of the payment service providers internal services fails or when the bank reports a 4xx error, this header is not populated. The absence of this response header should be interpreted as "token-external-error": "false".

  - `error.errorCode` (string, required)
    This is a textual error code categorising the error.
    Example: "InternalServerError"

  - `error.message` (string, required)
    A description of the error.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 501 fields (application/json):

  - `error` (object, required)
    The operation was not implemented, supported or enabled by the bank.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The operation was not implemented,supported or enabled by the bank.
    Example: "Not implemented."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 503 fields (application/json):

  - `error` (object, required)
    Service is unavailable, likely due to a transient condition; this is usually corrected with a retry.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The service is unavailable, likely due to a transient condition; this is usually corrected with a retry.
    Example: "Unavailable"

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"

## Response 504 fields (application/json):

  - `error` (object, required)
    The deadline expired before the operation could complete.

  - `error.errorCode` (string, required)
    A textual error code categorising the error.
    Example: "InternalServerError"

  - `error.paymentId` (string, required)
    The deadline expired before the operation could complete.
    Example: "Deadline exceeded."

  - `error.message` (string, required)
    A description of the error that occurred and a possible way to fix it.
    Example: "This is a description of the error."

  - `error.tokenTraceId` (string)
    The trace identifier for the given call.
    Example: "5678912345"