> 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. If the role is omitted (GET /v1/fin-insts), defaults to any.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"Financial Institutions","description":"Reference data for PSPs, FXPs, and SAPs, searchable by country, role, or institution ID."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["institutions.read"]}],"components":{"securitySchemes":{"nexusOAuth":{"type":"oauth2","description":"OAuth2 client credentials token issued per participant.","flows":{"clientCredentials":{"tokenUrl":"https://auth.nexus.net/realms/nexus/protocol/openid-connect/token","scopes":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","fxp.payment.read":"Query the FXP's own completed payments","rates.read":"Read FXP rate records.","rates.write":"Create or withdraw FXP rate records.","tiers.read":"Read FXP tier records.","tiers.write":"Create or withdraw FXP tier records.","relationships.read":"Read FXP–PSP relationship records.","relationships.write":"Create, update, or delete FXP–PSP relationship records."}}}}},"schemas":{"FinancialInstitutionsPageResponse":{"type":"object","description":"Cursor-paged response of financial institutions.","properties":{"finInsts":{"type":"array","description":"Financial institution items.","items":{"$ref":"#/components/schemas/FinancialInstitutionResponse"}},"nextCursor":{"type":"string","description":"Cursor for the next page."}},"required":["finInsts"]},"FinancialInstitutionResponse":{"type":"object","description":"Financial institution details.","properties":{"name":{"type":"string","description":"Financial institution name."},"finInstId":{"$ref":"#/components/schemas/FinancialInstitutionIdResponse","description":"Financial institution identifiers."},"countryCode":{"type":"string","description":"The ISO 3166 alpha-2 country code","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"roles":{"type":"array","description":"Financial institution roles.","items":{"type":"string","enum":["psp","fxp","sap"]}}}},"FinancialInstitutionIdResponse":{"type":"object","description":"Financial institution identifiers.","properties":{"bicfi":{"type":"array","items":{"type":"string","description":"BICFI identifier."}},"lei":{"type":"string","description":"LEI identifier."},"otherId":{"type":"array","description":"Other identifier values.","items":{"type":"string"}}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/fin-insts/{finInstRole}":{"get":{"tags":["Financial Institutions"],"summary":"Get Financial Institutions by Role","description":"Returns a list of financial institutions available in Nexus, for the specified role, for all countries. If the role is omitted (GET /v1/fin-insts), defaults to any.","operationId":"listFinancialInstitutionsByRole","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"finInstRole","in":"path","description":"One of psp, fxp, sap, any. Defaults to any if blank.","required":true,"schema":{"type":"string","enum":["psp","fxp","sap","any"]}},{"name":"cursor","in":"query","description":"Opaque cursor for the next page ordered by country code and name.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Number of results per page.","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialInstitutionsPageResponse"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```

## 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 API","version":"v1"},"tags":[{"name":"Financial Institutions","description":"Reference data for PSPs, FXPs, and SAPs, searchable by country, role, or institution ID."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["institutions.read"]}],"components":{"securitySchemes":{"nexusOAuth":{"type":"oauth2","description":"OAuth2 client credentials token issued per participant.","flows":{"clientCredentials":{"tokenUrl":"https://auth.nexus.net/realms/nexus/protocol/openid-connect/token","scopes":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","fxp.payment.read":"Query the FXP's own completed payments","rates.read":"Read FXP rate records.","rates.write":"Create or withdraw FXP rate records.","tiers.read":"Read FXP tier records.","tiers.write":"Create or withdraw FXP tier records.","relationships.read":"Read FXP–PSP relationship records.","relationships.write":"Create, update, or delete FXP–PSP relationship records."}}}}},"schemas":{"FinancialInstitutionResponse":{"type":"object","description":"Financial institution details.","properties":{"name":{"type":"string","description":"Financial institution name."},"finInstId":{"$ref":"#/components/schemas/FinancialInstitutionIdResponse","description":"Financial institution identifiers."},"countryCode":{"type":"string","description":"The ISO 3166 alpha-2 country code","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"roles":{"type":"array","description":"Financial institution roles.","items":{"type":"string","enum":["psp","fxp","sap"]}}}},"FinancialInstitutionIdResponse":{"type":"object","description":"Financial institution identifiers.","properties":{"bicfi":{"type":"array","items":{"type":"string","description":"BICFI identifier."}},"lei":{"type":"string","description":"LEI identifier."},"otherId":{"type":"array","description":"Other identifier values.","items":{"type":"string"}}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/countries/{countryCode}/fin-insts/{finInstRole}":{"get":{"tags":["Financial Institutions"],"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.","operationId":"listFinancialInstitutionsByCountryAndRole","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"countryCode","in":"path","description":"ISO 3166-1 alpha-2 (e.g., SG).","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"finInstRole","in":"path","description":"psp, fxp, sap, any (optional, defaults any).","required":true,"schema":{"type":"string","enum":["psp","fxp","sap","any"]}},{"name":"If-None-Match","in":"header","description":"Optional. ETag value from a previous response for conditional GET. If it matches the current entity tag, the server returns 304 Not Modified with no body.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Financial institutions retrieved.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FinancialInstitutionResponse"}}}}},"304":{"description":"Not Modified. The resource has not changed since the last request.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```

## 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. Supports HTTP conditional GET via If-None-Match header.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"Financial Institutions","description":"Reference data for PSPs, FXPs, and SAPs, searchable by country, role, or institution ID."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["institutions.read"]}],"components":{"securitySchemes":{"nexusOAuth":{"type":"oauth2","description":"OAuth2 client credentials token issued per participant.","flows":{"clientCredentials":{"tokenUrl":"https://auth.nexus.net/realms/nexus/protocol/openid-connect/token","scopes":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","fxp.payment.read":"Query the FXP's own completed payments","rates.read":"Read FXP rate records.","rates.write":"Create or withdraw FXP rate records.","tiers.read":"Read FXP tier records.","tiers.write":"Create or withdraw FXP tier records.","relationships.read":"Read FXP–PSP relationship records.","relationships.write":"Create, update, or delete FXP–PSP relationship records."}}}}},"schemas":{"FinancialInstitutionResponse":{"type":"object","description":"Financial institution details.","properties":{"name":{"type":"string","description":"Financial institution name."},"finInstId":{"$ref":"#/components/schemas/FinancialInstitutionIdResponse","description":"Financial institution identifiers."},"countryCode":{"type":"string","description":"The ISO 3166 alpha-2 country code","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"roles":{"type":"array","description":"Financial institution roles.","items":{"type":"string","enum":["psp","fxp","sap"]}}}},"FinancialInstitutionIdResponse":{"type":"object","description":"Financial institution identifiers.","properties":{"bicfi":{"type":"array","items":{"type":"string","description":"BICFI identifier."}},"lei":{"type":"string","description":"LEI identifier."},"otherId":{"type":"array","description":"Other identifier values.","items":{"type":"string"}}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/fin-insts/any/{finInstIdType}/{finInstId}":{"get":{"tags":["Financial Institutions"],"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. Supports HTTP conditional GET via If-None-Match header.","operationId":"getFinancialInstitutionById","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"finInstIdType","in":"path","description":"BICFI, LEI, otherId.","required":true,"schema":{"type":"string","enum":["BICFI","LEI","otherId"]}},{"name":"finInstId","in":"path","description":"Identifier value (format validated per type).","required":true,"schema":{"type":"string"}},{"name":"If-None-Match","in":"header","description":"Optional. ETag value from a previous response for conditional GET. If it matches the current entity tag, the server returns 304 Not Modified with no body.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Financial institution retrieved.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialInstitutionResponse"}}}},"304":{"description":"Not Modified. The resource has not changed since the last request.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```