# PIS - Get List of ASPSPs source: https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/pis-get-list-of-aspsps/index.md ## Request overview {#request-overview} The goal of this request is to retrieve the list of available Account Servicing Payment Service Providers (ASPSPs) for the user to select from as part of the third party application. ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |-------------------------|------------|------------------|-----------------------------------| | /payments/aspsps | `POST` | N/A | Returns list of supported ASPSPs. | The following sequence diagram shows the flow for a Third-Party Provider (TPP) to get a list of available ASPSPs. Diagram get_list_aspsp_pis ## Request scenario {#request-scenario} API Reference: `POST /payments/aspsps` #### Request header {#request-header} N/A #### Request body {#request-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |------------------------|------------------------------------------------------------------------------------|-----------------|---------------------------------------------------------------------------------------|---------------|------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------| | `requestInfo` | Includes information about request being processed | MC | This element encapsulates all request information sent to the API Service | M | 1..1 | Object | Set of elements used to define the request details | - | | `xRequestId` | ID of the request, unique to the call, as determined by the TPP | TPP | A memorable ID could be used to support in a dispute | M | 1..1 | UUID | Free field that allows for the addition of information that can be referenced for future use | 36 | | `id` | ID of a financial institution servicing the Accounts of the PSU | MC | A filter parameter could be used to filter ASPSPs by ASPSP id | O | 0..1 | String | Filter by internal id of ASPSP, exact match pattern | 1-256 | | `name` | Name of a financial institution servicing the Accounts of the PSU | MC | A filter parameter could be used to filter ASPSPs by ASPSP name | O | 0..1 | String | Filter by name of ASPSP, partial matching, non-case sensitive | 1-256 | | `country` | Country in which a financial institution servicing the Accounts of the PSU resides | MC | A filter parameter could be used to filter ASPSPs by country code | O | 0..1 | String | Filter by country code (ISO 3166 Alpha 2), exact match pattern, case sensitive, upper case | ISO 3166 ALPHA 2 CHAR | | `returnAdditionalData` | A parameter which drives the additional fields included in message response | MC | This element is used to specify which additional fields could be included in response | O | 0..1 | Enum | Specifies additional fields for ASPSP object which could be included in response. TPPs should check regularly as information is being updated as it becomes available. | Enum: `capabilities`, `logo`, `health`, `credentials` | | `limit` | Shows number of ASPSPs per page | TPP | Pagination parameter that sets the amount of ASPSPs which should be loaded per page | O | 0..1 | Integer | Specifies ASPSPs limit on pagination. The "limit" should be less or equal to 1000. If the "limit" is not included in the GET ASPSP list request, then it will be set to default value of 1000 items per page. | `$int32`, Minimum: 1 | | `offset` | Represents pagination offset | TPP | Pagination parameter that indicates the ASPSP from which to load the next batch | O | 0..1 | String | Specifies page offset, from which the bank is to get the list of ASPSPs. First request would contain a Null offset, then it should be the value from the response of previous request. | minLength: 1 | Tip: For an explanation of notations used, refer to **Open Banking General FAQ** in our [Frequently Asked Questions](https://developer.mastercard.com/open-banking-connect/documentation/frequently-asked-questions/index.md) section. ### Response -- Success {#response--success} HTTP Response Code = 200, OK Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). For specific error codes for this feature see **Feature specific error codes** below. #### Response header {#response-header} N/A #### Response body {#response-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |---------------------------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|------------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `originalRequestInfo` | Returns original request information to the TPP | MC | This object contains original request information | M | 1..1 | Object | Original request information received from the TPP | N/A | | `xRequestId` | A memorable ID which could be used to support in a dispute | TPP | This element could be used for request-response tracking | M | 1..1 | String UUID | Original `xRequestId` given by the client on request | 36 | | `aspsps` | The list of financial institutions which holds PSU accounts | TPP | List of ASPSPs | M | 1..\* | Object | Set of elements used to define the ASPSPs details | N/A | | `id` | ID of a financial institution servicing the Accounts of the PSU | TPP | Identification of ASPSP | O | 0..1 | String | Specifies the identification code of a financial institution which holds PSU accounts | 1-256 | | `name` | Name of a financial institution servicing the Accounts of the PSU | TPP | Name of ASPSP | O | 0..1 | String | Specifies the name of a financial institution which holds PSU accounts | 1-256 | | `aspspServices` | List of ASPSP supported services | TPP | Name of provided services | O | 0..1 | Enum | ASPSP provided services | 1-256 Enum: AIS, PIS, COF AIS - account information service, PIS - payment initiation service COF- confirmation of funds | | `profile` | Depending of ASPSP supported profile different fields can be available in API endpoints | TPP | Name of supported profile | O | 0..1 | String | The Open Banking API standard implemented on the side of the ASPSP. ASPSP supported profiles: `CMA9`, `PolishAPI`, `NextGenPSD2`, `STET`, `Czech Open Banking Standard`, `Slovak Banking API Standard`, `Budapest Bank` | | | `country` | Country in which a financial institution resides | TPP | Country code | O | 0..1 | String | Examples of ASPSP supported country code: `GB`, `PL`, `AT`, `BE`, `BG`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `IT`, `GR`, `HU`, `HR`, `NL`, `LV`, `LU`, `RO`, `SE`, `SI` | ISO 3166 ALPHA 2 CHAR | | `capabilities` | Contains the list of ASPSP capabilities related to an API profile | TPP | List of capabilities | O | 0..1 | Object | Set of elements used to define the capabilities related to API profile assigned to ASPSP (Dictionary map) | N/A | | `any<\*>` | Capabilities names and availability status details | TPP | Capability name and availability status | O | 0..\* | Tuple(String, Boolean) | Data map `` for ++ capabilities | | | `logo` | Contains ASPSP logo information | TPP | Logo information | O | 0..1 | Object | Set of elements used to define the logo metadata and image content (Dictionary map) | N/A | | `fileType` | File type to store logo images | TPP | Type of logo image file | O | 0..1 | Enum | Logo image file format. Supports the following image file formats: `jpg`, `png`, `svg` | Enum: `png`, `jpg`, `svg` | | `binaryContent` | Contains ASPSP's logo image in binary format | TPP | Binary content of the image | O | 0..1 | String | Binary content of the ASPSP logo image file in Base64 encoding (deprecated) | Deprecated | | `logoURL` | Returns URL link to ASPSP logo image file | TPP | URL to logo image file | O | 0..1 | String | The URL link to ASPSP logo image file | | | `credentialFields` | Provide the list of credential fields required by the ASPSP during PSU authorization via embedded flow | TPP | List of credential fields | O | 0..\* | Object | Object containing the fields which ASPSP requires for PSU authorization via embedded flow | - | | `health` | Returns ASPSP health status | TPP | Health status | O | 0..1 | Object | Health status of banks in regards with OBC API connectivity | | | `aisStatus` | Returns status of Account Information Service requests | TPP | AIS requests status | O | 0..1 | Enum | Current status of the ASPSP for Account Information Service requests | Enum: \[LIVE, DOWN, NO CALLS\] | | `pisStatus` | Returns status of Payment Initiation Service requests | TPP | PIS requests status | O | 0..1 | Enum | Current status of the ASPSP for Payment Initiation Service requests | Enum: \[LIVE, DOWN, NO CALLS\] | | `lastUpdatedAt` | Contains timestamp of record last update | TPP | Last update time of the record | O | 0..1 | String | Connector's timestamp when the record was last updated | date-time | | `fieldsFormatInformation` | Returns restrictions required for specific fields to be sent in consent request for payment initiation | TPP | Validate value of specific fields | O | 0..1 | Object | List of fields format restrictions required by an ASPSP | | | `field` | Identifies the field from OBC API that has a value restriction | TPP | Required to identify which field has a restriction | O | 0..1 | String | A field from OBC API which has a restriction required by an ASPSP | | | `constraint` | Communicates the restriction rule in regex format that validates value of a field before sending as part of the consent request | TPP | Get regex rule to validate field value | O | 0..1 | String | The field format required by an ASPSP | | | `mandatoryFields` | Contains paths of fields required by ASPSP to be included in AIS consent request and/or PIS consent request | TPP | Fields that have a prefix of "access:" are required to be included in AIS consent request. Other fields are required to be included in the PIS consent request | O | 0..1 | String | List of fields that are required by an ASPSP | Depending on the prefix before the field's path, the field is required to be included in consent request for either domestic (prefix "domestic:") or SEPA payment within the debtor's bank country ("sepaLocal:") or SEPA payment going to a bank outside debtor's bank (prefix "sepaCrossBorder:") or cross border payments (prefix "crossBorder:") or AIS consent (prefix "access:") | | `offset` | Page offset | TPP | Offset used in the next request to get next page | O | 0..1 | String | The next ASPSP from which should be requested the next batch of ASPSPs. This contains the ID of the ASPSP. | - | | `allLogos` | Contains information for all available ASPSP logos. | TPP | Logo information | O | 0..1 | Array of objects | Set of elements used to define the logo metadata and all images content (Dictionary map). | - | | `fileType` | File type to store logo images | TPP | Type of logo image file | O | 0..1 | Enum | Logo image file format. Supports the following image file formats: jpg, png, svg. | Enum: \[png, jpg, svg\] | | `logoURL` | Returns URL link to ASPSP logo image file. | TPP | URL to logo image file | O | 0..1 | String | The URL link to ASPSP logo image file | | #### Response example {#response-example} When a TPP requests capabilities to be returned, the Open Banking Connect API will reply with a list of capabilities that are available for the API profile assigned to the ASPSP. Below is an example of a response containing such a list. ```json { "id": "58ff8e35-b783-4169-a59e-f916036c2a43", "name": "Ozone Modelo Test Bank", "aspspServices": [ "PIS", "AIS", "COF" ], "profile": "CMA9", "country": "GB", "capabilities": { "obtain_raw_consent_pis": true, "retrieve_crossborder_pi_status": true, "obtain_domestic_consent": true, "initiate_crossborder_payment": true, "obtain_ais_consent": true, "retrieve_transactions": true, "standing_order_info": true, "retrieve_accounts": true, "delete_ais_consent": true, "obtain_crossborder_consent": true, "retrieve_balances": true, "retrieve_account_details": true, "retrieve_domestic_pi_status": true, "initiate_domestic_payment": true, "obtain_raw_consent": true } } ``` ## Feature specific error codes {#feature-specific-error-codes} Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|-----------------------------------------------------------------------------|----------------------------------------------------------------------| | "limit is greater than the maximum allowed page size. Maximum allowed page size is ``" | `FORMAT_ERROR` | The limit is greater than the maximum allowed page size. The maximum allowed page size is ``. The maximum page size default value is configurable. | n/a | Typically occurs because "limit" is greater than maximum allowed page size. | Set a value of limit less or equal to the maximum allowed page size. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "limit is greater than the maximum allowed page size. Maximum allowed page size is 1000", } ] } } ```