# Get banks v1

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

Endpoint: GET /banks
Security: Bearer, BasicAuth

## Query parameters:

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

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

  - `sort` (string)
    The key to sort the result. This can be name (i.e., bank name), provider, or country.
    Example: "country"

  - `memberId` (string)
    The Token.io-assigned member id of the TPP.
    Example: "m:nP4w3u5y8ddrxDJkjimgSX9e4fZ:5zKtXEAq"

  - `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.
    Example: ["goldbank","opalbank","platinumbank"]

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

  - `tppId` (string)
    Filters for banks for which the TPP represented by this tppId has access.
    Example: "4h27g823-g73s-07v3-l49s-prte94bf21v"

  - `providers` (array)
    Filters for banks that are accessed through any of the listed providers.
    Example: "Token.io"

  - `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.
    Example: "NBAGDE3E"

  - `countries` (array)
    Filters for banks that are located in the countries specified by this list of two-letter country codes in upper case (ISO 3166-1 alpha-2).
    Example: ["IT","DE","RO"]

  - `bank_features.supports_send_payment.value` (boolean)
    Filters for banks that support payment initiation.

  - `bank_features.supports_receive_payment.value` (boolean)
    Filters for banks that support receiving payments.

  - `bank_features.supports_balance.value` (boolean)
    Filters for the banks that support retrieving balances.

  - `bank_features.supports_scheduled_payment.value` (boolean)
    Filters for banks that support future dated scheduled payments.

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

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

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

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

  - `bank_features.supports_transactions_date_filter.value` (boolean)
    Filters for banks that support retrieving transactions by date filter.

  - `bank_features.supports_account_information.value` (boolean)
    Filters for banks that support retrieval of account information.

  - `bank_features.supports_single_payment.value` (boolean)
    Filters for banks that support single immediate payments.

  - `bank_features.supports_variable_recurring_payment.value` (boolean)
    Filters for banks that support variable recurring payments.

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

  - `supportedPaymentNetworks` (array)
    Filters for banks that support any of the listed payment networks.

  - `bankGroup` (string)
    Filters for banks that are part 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"]

## Response 200 fields (application/json):

  - `banks` (array)
    Contains information for each bank matching the request criteria.

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

  - `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.countries` (array)
    A list of two-letter country codes in upper case (ISO 3166-1 alpha-2), in which this bank operates.
    Example: ["DE","IT","GB"]

  - `banks.credentialFields` (object)

  - `banks.credentialFields.fields` (array)
    Contains information used in embedded authentication flows. These are optional credential request fields. When provided, the TPP should call initiateBankAuth again to provide the credentials.

  - `banks.credentialFields.fields.description` (string)
    The description of the credentials.
    Example: "User authentication"

  - `banks.credentialFields.fields.displayName` (string)
    The display name for the credentials.
    Example: "Client ID"

  - `banks.credentialFields.fields.flickerCode` (string)
    The Flicker code displayed to the user.
    Example: "FLICKERCODE"

  - `banks.credentialFields.fields.id` (string)
    Specifies the identifier to be used when passing the value for this credential.
    Example: "clientId"

  - `banks.credentialFields.fields.image` (string)
    A Base64 representation of an image displayed to the user.
    Example: "YWJAeXoyWhAeXohteQ"

  - `banks.credentialFields.fields.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.
    Example: ["SMS","Phone call"]

  - `banks.credentialFields.fields.type` (string)
    Specifies the type of credential.
    Enum: "INVALID", "FIELD", "PASSWORD", "PSU_MESSAGE", "IMAGE", "FLICKER", "DECOUPLED"

  - `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.name` (string)
    The name of the field in the Token.io requestpayload with bank-imposed formatting constraints.
    Example: "description"

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

  - `banks.fullLogoUri` (string)
    The URI of the location of the full size bank icon.
    Example: "https://s3-us-west-2.amazonaws.com/tokenio-assets/1.0.0/logos/gold/gold_full.png"

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

  - `banks.identifier` (string)
    The optional identifier for the bank. This is not guaranteed to be unique across all banks.
    Example: "BLZ"

  - `banks.logoUri` (string)
    The URI of the location of the square bank avatar icon.
    Example: "https://s3-us-west-2.amazonaws.com/tokenio-assets/1.0.0/logos/gold/gold_square.png"

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

  - `banks.mandatoryFields.access` (object)
    Specifies the mandatory fields for an access token request.

  - `banks.mandatoryFields.access.domestic` (object)
    Specifies the mandatory fields for an access request.

  - `banks.mandatoryFields.access.domestic.fields` (array)
    The full path to the field within the domestic access request.
    Example: ["access_body.instructions.access_destinations.customer_data.legal_names","access_body.instructions.source.bic","access_body.instructions.source.account_identifier"]

  - `banks.mandatoryFields.access.domestic.PolishApiFields` (array)
    Lists other Polish API fields which must be included in the domestic access request.
    Example: "access_body.instructions.metadata.provider_access_metadata.polish_api_access_metadata.delivery_mode"

  - `banks.mandatoryFields.access.domestic.StetFields` (array)
    Lists other STET API fields which must be included in the domestic access request.
    Example: "access_body.instructions.metadata.provider_access_metadata.stet_access_metadata.beneficiary.creditor_agent"

  - `banks.mandatoryFields.access.international` (object)
    Specifies the mandatory fields for an international access request.

  - `banks.mandatoryFields.access.international.fields` (array)
    The full path to the field within the international access request.
    Example: ["access_body.instructions.access_destinations.customer_data.legal_names","access_body.instructions.source.bic","access_body.instructions.source.account_identifier"]

  - `banks.mandatoryFields.access.international.PolishApiFields` (array)
    Lists other Polish API fields which must be included in the access request.
    Example: "access_body.instructions.metadata.provider_access_metadata.polish_api_access_metadata.delivery_mode"

  - `banks.mandatoryFields.access.international.StetFields` (array)
    Lists other STET API fields which must be included in the access request.
    Example: "access_body.instructions.metadata.provider_access_metadata.stet_access_metadata.beneficiary.creditor_agent"

  - `banks.mandatoryFields.standingOrder` (object)
    Specifies the mandatory fields for a standing order token request.

  - `banks.mandatoryFields.standingOrder.domestic` (object)
    Specifies the mandatory fields for a domestic standing order.

  - `banks.mandatoryFields.standingOrder.domestic.fields` (array)
    The full path to the field within the domestic standing order.
    Example: ["standing_order_body.instructions.transfer_destinations.customer_data.legal_names","standing_order_body.instructions.source.bic","standing_order_body.instructions.source.account_identifier"]

  - `banks.mandatoryFields.standingOrder.domestic.PolishApiFields` (array)
    Lists other Polish API fields which must be included in the domestic standing order.
    Example: "standing_order_body.instructions.metadata.provider_transfer_metadata.polish_api_transfer_metadata.delivery_mode"

  - `banks.mandatoryFields.standingOrder.domestic.StetFields` (array)
    Lists other STET API fields which must be included in the domestic standing order.
    Example: "standing_order_body.instructions.metadata.provider_transfer_metadata.stet_transfer_metadata.beneficiary.creditor_agent"

  - `banks.mandatoryFields.standingOrder.international` (object)
    Specifies the mandatory fields for an international standing order.

  - `banks.mandatoryFields.standingOrder.international.fields` (array)
    The full path to the field within the international standing order.
    Example: ["standing_order_body.instructions.transfer_destinations.customer_data.legal_names","standing_order_body.instructions.source.bic","standing_order_body.instructions.source.account_identifier"]

  - `banks.mandatoryFields.standingOrder.international.PolishApiFields` (array)
    Lists other Polish API fields which must be included in the international token request.
    Example: "standing_order_body.instructions.metadata.provider_transfer_metadata.polish_api_transfer_metadata.delivery_mode"

  - `banks.mandatoryFields.standingOrder.international.StetFields` (array)
    Lists other STET API fields which must be included in the international token request.
    Example: "standing_order_body.instructions.metadata.provider_transfer_metadata.polish_api_transfer_metadata.delivery_mode"

  - `banks.mandatoryFields.transfer` (object)
    Specifies the mandatory fields for a transfer token request.

  - `banks.mandatoryFields.transfer.domestic` (object)
    Specifies the mandatory fields for a domestic transfer.

  - `banks.mandatoryFields.transfer.domestic.fields` (array)
    The full path to the field within the domestic transfer.
    Example: ["transfer_body.instructions.transfer_destinations.customer_data.legal_names","transfer_body.instructions.source.bic","transfer_body.instructions.source.account_identifier"]

  - `banks.mandatoryFields.transfer.domestic.PolishApiFields` (array)
    Lists other Polish API fields which must be included in the domestic transfer.
    Example: "transfer_body.instructions.metadata.provider_transfer_metadata.polish_api_transfer_metadata.delivery_mode"

  - `banks.mandatoryFields.transfer.domestic.StetFields` (array)
    Lists other STET API fields which must be included in the domestic transfer.
    Example: "transfer_body.instructions.metadata.provider_transfer_metadata.stet_transfer_metadata.beneficiary.creditor_agent"

  - `banks.mandatoryFields.transfer.international` (object)
    Specifies the mandatory fields for an international transfer.

  - `banks.mandatoryFields.transfer.international.fields` (array)
    The full path to the field within the international transfer.
    Example: ["transfer_body.instructions.transfer_destinations.customer_data.legal_names","transfer_body.instructions.source.bic","transfer_body.instructions.source.account_identifier"]

  - `banks.mandatoryFields.transfer.international.PolishApiFields` (array)
    Lists other Polish API fields which must be included in the international transfer.
    Example: "transfer_body.instructions.metadata.provider_transfer_metadata.polish_api_transfer_metadata.delivery_mode"

  - `banks.mandatoryFields.transfer.international.StetFields` (array)
    Lists other STET API fields which must be included in the international transfer.
    Example: "transfer_body.instructions.metadata.provider_transfer_metadata.stet_transfer_metadata.beneficiary.creditor_agent"

  - `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.name` (string)
    The commonly recognised name of the bank.
    Example: "Gold Bank"

  - `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.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.provider` (string)
    Open Banking SaaS adapter or provider.
    Example: "Token.io"

  - `banks.requiresExternalAuth` (boolean)
    The bank connection requires external authorization for creating transfers.

  - `banks.requiresOneStepPayment` (boolean)
    The bank connection only supports immediate redemption of transfer tokens.

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

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

  - `banks.supportsBalance` (boolean)
    The bank connection supports the retrieval of balances.

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

  - `banks.supportsAccountInformation` (boolean)
    The bank connection supports retrieval of information through Account Information Services (AIS).

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

  - `banks.supportsReturnRefundAccount` (boolean)
    The bank connection supports the return of refunds.

  - `banks.supportsScheduledPayment` (boolean)
    The bank connection supports future dated payments.

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

  - `banks.supportsStandingOrder` (boolean)
    The bank connection supports scheduled recurring payments.

  - `banks.supportsTransactionsDateFilter` (boolean)
    The bank connection supports specifying startDate and endDate for filtering transaction lookups.

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

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

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

  - `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)
    Sort banks by the value of 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` (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 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 404 fields (application/json):

  - `error` (object, required)
    The error object returned when given payment cannot be found: ResourceNotFound.

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

  - `error.paymentId` (string, required)
    The requested entity, the paymentID, was not found.
    Example: "pm2:12345abcd:abcde"

  - `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 429 fields (application/json):

  - `error` (object, required)
    Resource exhausted. Too many requests.

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

  - `error.paymentId` (string, required)
    The maximum number of requests has been reached.
    Example: "Resource exhausted. Check quota."

  - `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"