> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/apis/financial-institutions.md).

# Financial Institutions

## Get Financial Institutions by Role

> Returns a list of financial institutions available in Nexus, for the specified role, for all countries.

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"Financial Institutions (PSPs, FXPs and SAPs)","description":"Retrieve financial institutions by type or ID"}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/fin-insts/{finInstRole}":{"get":{"summary":"Get Financial Institutions by Role","description":"Returns a list of financial institutions available in Nexus, for the specified role, for all countries.","parameters":[{"name":"finInstRole","in":"path","description":"The type of financial institution (PSPs, FXPs, SAPs). If set to any, all financial institutions in Nexus will be returned. (Results will be paged.)","required":true,"schema":{"type":"string","enum":["psp","fxp","sap","any"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{}}},"400":{"description":"Unsupported role. Reason code BE016 FI_ROLE_UNSUPPORTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Authentication failed. Applicable reason codes: AE001 AUTH_TOKEN_MISSING, AE002 AUTH_TOKEN_INVALID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Authorization failed. The token is valid but its OAuth2 scopes do not grant access to this endpoint or corridor. Reason code AE004 ACCESS_DENIED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"An unhandled exception or infrastructure failure occurred. Reason code TE099 INTERNAL_ERROR. The caller may retry with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}},"tags":["Financial Institutions (PSPs, FXPs and SAPs)"],"operationId":"listFinInsts"}}}}
```

## Get Financial Institutions (PSPs, FXPs, SAPs or all) in a specified country

> Returns a list of financial institutions (PSPs, FXPs, SAPs or all) operating in the specified country, who are connected to an IPS that is a member of Nexus. The list also includes those PSPs who are not members of Nexus. The data can be used (for example) to populate a drop-down list of PSPs (rather than requiring the Sender to enter a BIC directly). If {finInstRole} is set to any or left blank, all PSPs, FXPs and SAPs are returned.

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"Financial Institutions (PSPs, FXPs and SAPs)","description":"Retrieve financial institutions by type or ID"}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/countries/{countryCode}/fin-insts/{finInstRole}":{"get":{"summary":"Get Financial Institutions (PSPs, FXPs, SAPs or all) in a specified country","description":"Returns a list of financial institutions (PSPs, FXPs, SAPs or all) operating in the specified country, who are connected to an IPS that is a member of Nexus. The list also includes those PSPs who are not members of Nexus. The data can be used (for example) to populate a drop-down list of PSPs (rather than requiring the Sender to enter a BIC directly). If {finInstRole} is set to any or left blank, all PSPs, FXPs and SAPs are returned.","parameters":[{"name":"countryCode","in":"path","description":"The ISO 3166 alpha-2 country code","required":true,"schema":{"type":"string"}},{"name":"finInstRole","in":"path","description":"The type of financial institution (PSPs, FXPs or SAPs). If omitted or set to any, all PSPs, FXPs and SAPS in that country will be returned.","required":true,"schema":{"type":"string","enum":["psp","fxp","sap","any"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{}}},"400":{"description":"Invalid request. Applicable reason codes: BE016 FI_ROLE_UNSUPPORTED, BE017 FI_COUNTRY_INVALID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Authentication failed. Applicable reason codes: AE001 AUTH_TOKEN_MISSING, AE002 AUTH_TOKEN_INVALID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Authorization failed. The token is valid but its OAuth2 scopes do not grant access to this endpoint or corridor. Reason code AE004 ACCESS_DENIED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"404":{"description":"No institutions found. Reason code BE018 FI_COUNTRY_NO_INSTITUTIONS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"An unhandled exception or infrastructure failure occurred. Reason code TE099 INTERNAL_ERROR. The caller may retry with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}},"tags":["Financial Institutions (PSPs, FXPs and SAPs)"],"operationId":"listFinInstsByCountry"}}}}
```

## Get Financial Institution by Financial Institution ID

> Returns a Financial Institution (including PSP, FXP and SAP) based on a specified type of financial institution ID.<br>

```json
{"openapi":"3.1.0","info":{"title":"Nexus APIs","version":"0.3.1"},"tags":[{"name":"Financial Institutions (PSPs, FXPs and SAPs)","description":"Retrieve financial institutions by type or ID"}],"servers":[{"url":"http://localhost:8080","description":"Local development"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Nexus simulator"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ErrorResultDto":{"type":"object","description":"Structured business rejection returned for all error responses. This response is only returned for rejection cases; the statusCode is always RJCT.","properties":{"statusCode":{"type":"string","enum":["RJCT"],"description":"Business level status code indicating the outcome. Always RJCT (Rejected)."},"reasonCode":{"type":"string","pattern":"^(TE|AE|BE)[A-Z0-9]*$","description":"Categorised reason code with a prefix indicating the error category: TE for Technical Error, AE for Authentication Error, BE for Business Error."},"name":{"type":"string","description":"Machine readable business error name from the error catalogue."},"description":{"type":"string","description":"Human readable error description."}},"required":["statusCode","reasonCode","name","description"]}}},"paths":{"/v1/fin-insts/any/{finInstIdType}/{finInstId}":{"get":{"summary":"Get Financial Institution by Financial Institution ID","description":"Returns a Financial Institution (including PSP, FXP and SAP) based on a specified type of financial institution ID.\n","parameters":[{"name":"finInstIdType","in":"path","description":"The type of financial institution ID (e.g., BICFI, LEI, otherId OR internalId (for Nexus's internal pspId)).","required":true,"schema":{"type":"string"}},{"name":"finInstId","in":"path","description":"The financial institution ID value.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{}}},"400":{"description":"Unsupported identifier type. Reason code BE019 FI_ID_TYPE_UNSUPPORTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"401":{"description":"Authentication failed. Applicable reason codes: AE001 AUTH_TOKEN_MISSING, AE002 AUTH_TOKEN_INVALID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"403":{"description":"Authorization failed. The token is valid but its OAuth2 scopes do not grant access to this endpoint or corridor. Reason code AE004 ACCESS_DENIED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"404":{"description":"No institution found for the specified financial institution ID. Reason code BE020 FI_NOT_FOUND.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}},"429":{"description":"Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry."},"500":{"description":"An unhandled exception or infrastructure failure occurred. Reason code TE099 INTERNAL_ERROR. The caller may retry with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResultDto"}}}}},"tags":["Financial Institutions (PSPs, FXPs and SAPs)"],"operationId":"resolveFinInst"}}}}
```