> 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/nexus-payments-apis/financial-institutions.md).

# Financial Institutions

Reference data for PSPs, FXPs, and SAPs, searchable by country, role, or institution ID.

## 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.\
> \
> \---\
> \
> \#### Response validation rules\
> \
> \*\*200 OK\*\* — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\
> \
> \| Field | Type | Presence | Nullable | Constraints |\
> \|---|---|---|---|---|\
> \| \`finInsts\` | array | Required | N | — |\
> \| \`finInsts\[].name\` | string | Required | N | min length 1; max length 140 |\
> \| \`finInsts\[].finInstId\` | object | Required | N | — |\
> \| \`finInsts\[].finInstId.bicfi\` | array | Conditional — present when the institution has a BIC | Y | each item: pattern \`^\[A-Z]{6}\[0-9A-Z]{2}(\[0-9A-Z]{3})?$\`, max length 11 |\
> \| \`finInsts\[].finInstId.lei\` | string | Optional | Y | pattern \`^\[0-9A-Z]{18}\[0-9]{2}$\`; max length 20 |\
> \| \`finInsts\[].finInstId.otherId\` | array | Optional | Y | — |\
> \| \`finInsts\[].countryCode\` | string | Required | N | pattern \`^\[A-Z]{2}$\`; length 2 |\
> \| \`finInsts\[].roles\` | array | Required | N | each item: one of \`psp\`, \`fxp\`, \`sap\` |\
> \| \`nextCursor\` | string | Optional | Y | — |\
> \
> \*\*Cross-field rules\*\*\
> \
> \- Every item's \`roles\` contains the requested \`finInstRole\` (all roles when \`finInstRole\` = \`any\`).\
> \- \`finInstId.lei\` is \`null\` when no LEI is available; \`finInstId.otherId\` is an empty array when there are no other identifiers.\
> \
> \*\*Response signature\*\* — every 200 response carries \`Signature-Input\` and \`Signature\` and \`Content-Digest\` per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\
> \
> \*\*Error responses (4xx/5xx with a body)\*\* — the body MUST conform to \`ErrorApiResponse\`: \`statusCode\` = \`RJCT\`; \`reasonCode\` matches \`^\[A-Z]{2}\[0-9]{3}$\`; \`name\` is UPPER\_SNAKE\_CASE (≤ 50); \`description\` ≤ 500 characters and MUST NOT contain PII. \`reasonCode\` values for this operation: \`TE001\`, \`BE016\`, \`TE099\`, \`AE001\`, \`AE002\`, \`AE003\`, \`AE005\`, \`AE006\`, \`AE004\`. Gateway errors (405, 429, 502, 503, 504) carry no body.

```json
{"openapi":"3.1.0","info":{"title":"Nexus Payments API","version":"v1"},"tags":[{"name":"Financial Institutions","description":"Reference data for PSPs, FXPs, and SAPs, searchable by country, role, or institution ID."}],"servers":[{"url":"https://{environment}.payments.nexus.net","description":"Nexus participant-facing API endpoint. Resolved via Nexus private DNS over the established IPsec IKEv2 tunnel and not reachable from the public Internet.","variables":{"environment":{"default":"prod","enum":["pat","prod"],"description":"Deployment environment subdomain."}}}],"security":[{"mutualTLS":[],"nexusOAuth":["institutions.read"]}],"components":{"securitySchemes":{"mutualTLS":{"type":"mutualTLS","description":"Mutual TLS: the IPSO presents its X.509 client certificate on every connection, validated during the TLS handshake (fail-closed). The same certificate is the RFC 8705 binding anchor for the OAuth access token (see nexusOAuth)."}},"parameters":{"SignatureInputBodyless":{"name":"Signature-Input","in":"header","required":true,"description":"RFC 9421 signature metadata for a request without a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled `nexus` whose covered components are exactly `\"@method\" \"@authority\" \"@path\" \"@query\"`, followed by `\"if-none-match\"` when that header is sent. `@query` is always covered; an empty query serialises as `?`, so query parameters cannot be added or removed undetected. Signature parameters, emitted in this order: `created` and `expires` (Unix seconds; `expires` = `created` + 300; the receiver rejects `created` more than ±5 minutes from its clock or a signature past `expires`), `keyid` (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), `alg` (always `rsa-pss-sha512`) and `tag` (always `nexus-v1`). The signature parameters are signed through the `@signature-params` line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.","schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@method\" \"@authority\" \"@path\" \"@query\"( \"if-none-match\")?\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"Signature":{"name":"Signature","in":"header","required":true,"description":"RFC 9421 signature value: one dictionary member labelled `nexus` holding an RFC 8941 byte sequence - the **standard base64** (not base64url) RSASSA-PSS signature using SHA-512 (`rsa-pss-sha512`), computed over the RFC 9421 signature base built from the components and parameters declared in `Signature-Input`. Produced with the sender's own signing private key; the receiver verifies it against the sender's registered signing public key resolved from `keyid`. With the minimum RSA-3072 key the signature is 384 bytes, i.e. 512 base64 characters. A missing, malformed or non-verifying signature is rejected with AE005.","schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}}},"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","null"],"description":"Cursor for the next page."}},"required":["finInsts"]},"FinancialInstitutionResponse":{"type":"object","description":"Financial institution details.","properties":{"name":{"type":"string","description":"Financial institution name.","minLength":1,"maxLength":140},"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"]}}},"required":["countryCode","finInstId","name","roles"]},"FinancialInstitutionIdResponse":{"type":"object","description":"Financial institution identifiers.","properties":{"bicfi":{"type":["array","null"],"items":{"type":"string","description":"BICFI identifier.","maxLength":11,"pattern":"^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$"}},"lei":{"type":["string","null"],"description":"LEI identifier.","maxLength":20,"pattern":"^[0-9A-Z]{18}[0-9]{2}$"},"otherId":{"type":["array","null"],"description":"Other identifier values.","items":{"type":"string"}}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the Nexus authentication layer or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.\n\n#### Validation rules\n\n- All four fields are required and never `null`.\n- `statusCode`: always `RJCT`.\n- `reasonCode`: 5 characters matching `^[A-Z]{2}[0-9]{3}$`; family prefix `TE` (technical), `AE` (authentication/authorisation, enforced at authentication) or `BE` (business); one of the values enumerated in the `reasonCode` schema.\n- `name`: UPPER_SNAKE_CASE, 1–50 characters; the name paired with `reasonCode` (e.g. `TE001` ↔ `INVALID_REQUEST`).\n- `description`: 1–500 characters; MUST NOT contain PII.\n- 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,"minLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, AE001–AE006, enforced at authentication), BE (Business Error, BE001–BE031).","enum":["TE001","TE002","TE099","AE001","AE002","AE003","AE004","AE005","AE006","BE001","BE002","BE007","BE008","BE009","BE010","BE011","BE012","BE013","BE014","BE015","BE016","BE017","BE018","BE019","BE020","BE021","BE030","BE031"],"maxLength":5,"pattern":"^[A-Z]{2}[0-9]{3}$","minLength":5},"name":{"type":"string","description":"Machine-readable error name paired with the reason code.","maxLength":50,"pattern":"^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$","minLength":1},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII.","maxLength":500,"minLength":1}},"required":["description","name","reasonCode","statusCode"]}},"headers":{"ResponseSignatureInput":{"description":"RFC 9421 signature metadata for a GET response, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). Signed by the responding server with its own signing private key. Covered components: `\"@status\" \"content-type\" \"content-digest\"` on 200, or `\"@status\" \"etag\"` on 304, followed in both cases by the request-bound components `\"@method\";req \"@path\";req \"@query\";req`, which tie the response to the resource that was requested. Same `created`, `expires`, `keyid`, `alg` and `tag` rules as requests. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.","required":true,"schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@status\" (\"content-type\" \"content-digest\"|\"etag\") \"@method\";req \"@path\";req \"@query\";req\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"ResponseSignature":{"description":"RFC 9421 response signature: one dictionary member labelled `nexus` holding the standard base64 `rsa-pss-sha512` signature produced by the responding server over the signature base declared in the response `Signature-Input`. Verified by the client against the server's registered signing public key.","required":true,"schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}},"ResponseContentDigest":{"description":"RFC 9530 SHA-512 digest of the exact response body bytes, covered by the response signature.","required":true,"schema":{"type":"string","pattern":"^sha-512=:[A-Za-z0-9+/]{86}==:$"}}}},"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.\n\n---\n\n#### Response validation rules\n\n**200 OK** — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\n\n| Field | Type | Presence | Nullable | Constraints |\n|---|---|---|---|---|\n| `finInsts` | array | Required | N | — |\n| `finInsts[].name` | string | Required | N | min length 1; max length 140 |\n| `finInsts[].finInstId` | object | Required | N | — |\n| `finInsts[].finInstId.bicfi` | array | Conditional — present when the institution has a BIC | Y | each item: pattern `^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$`, max length 11 |\n| `finInsts[].finInstId.lei` | string | Optional | Y | pattern `^[0-9A-Z]{18}[0-9]{2}$`; max length 20 |\n| `finInsts[].finInstId.otherId` | array | Optional | Y | — |\n| `finInsts[].countryCode` | string | Required | N | pattern `^[A-Z]{2}$`; length 2 |\n| `finInsts[].roles` | array | Required | N | each item: one of `psp`, `fxp`, `sap` |\n| `nextCursor` | string | Optional | Y | — |\n\n**Cross-field rules**\n\n- Every item's `roles` contains the requested `finInstRole` (all roles when `finInstRole` = `any`).\n- `finInstId.lei` is `null` when no LEI is available; `finInstId.otherId` is an empty array when there are no other identifiers.\n\n**Response signature** — every 200 response carries `Signature-Input` and `Signature` and `Content-Digest` per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\n\n**Error responses (4xx/5xx with a body)** — the body MUST conform to `ErrorApiResponse`: `statusCode` = `RJCT`; `reasonCode` matches `^[A-Z]{2}[0-9]{3}$`; `name` is UPPER_SNAKE_CASE (≤ 50); `description` ≤ 500 characters and MUST NOT contain PII. `reasonCode` values for this operation: `TE001`, `BE016`, `TE099`, `AE001`, `AE002`, `AE003`, `AE005`, `AE006`, `AE004`. Gateway errors (405, 429, 502, 503, 504) carry no body.","operationId":"listFinancialInstitutionsByRole","parameters":[{"name":"Accept","in":"header","description":"*/*","required":true,"schema":{"type":"string","default":"*/*"}},{"$ref":"#/components/parameters/SignatureInputBodyless"},{"$ref":"#/components/parameters/Signature"},{"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"}}},"headers":{"Signature-Input":{"$ref":"#/components/headers/ResponseSignatureInput"},"Signature":{"$ref":"#/components/headers/ResponseSignature"},"Content-Digest":{"$ref":"#/components/headers/ResponseContentDigest"}}},"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 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.\
> \
> \---\
> \
> \#### Response validation rules\
> \
> \*\*200 OK\*\* — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\
> \
> \| Field | Type | Presence | Nullable | Constraints |\
> \|---|---|---|---|---|\
> \| \`name\` | string | Required | N | min length 1; max length 140 |\
> \| \`finInstId\` | object | Required | N | — |\
> \| \`finInstId.bicfi\` | array | Conditional — present when the institution has a BIC | Y | each item: pattern \`^\[A-Z]{6}\[0-9A-Z]{2}(\[0-9A-Z]{3})?$\`, max length 11 |\
> \| \`finInstId.lei\` | string | Optional | Y | pattern \`^\[0-9A-Z]{18}\[0-9]{2}$\`; max length 20 |\
> \| \`finInstId.otherId\` | array | Optional | Y | — |\
> \| \`countryCode\` | string | Required | N | pattern \`^\[A-Z]{2}$\`; length 2 |\
> \| \`roles\` | array | Required | N | each item: one of \`psp\`, \`fxp\`, \`sap\` |\
> \
> \*\*Cross-field rules\*\*\
> \
> \- \`finInstId\` contains the requested identifier under the requested \`finInstIdType\`.\
> \- \`finInstId.lei\` is \`null\` when no LEI is available; \`finInstId.otherId\` is an empty array when there are no other identifiers.\
> \
> \*\*Response signature\*\* — every 200 and 304 response carries \`Signature-Input\` and \`Signature\` (plus \`Content-Digest\` on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\
> \
> \*\*Error responses (4xx/5xx with a body)\*\* — the body MUST conform to \`ErrorApiResponse\`: \`statusCode\` = \`RJCT\`; \`reasonCode\` matches \`^\[A-Z]{2}\[0-9]{3}$\`; \`name\` is UPPER\_SNAKE\_CASE (≤ 50); \`description\` ≤ 500 characters and MUST NOT contain PII. \`reasonCode\` values for this operation: \`TE001\`, \`BE019\`, \`BE020\`, \`TE099\`, \`AE001\`, \`AE002\`, \`AE003\`, \`AE005\`, \`AE006\`, \`AE004\`. Gateway errors (405, 429, 502, 503, 504) carry no body.

```json
{"openapi":"3.1.0","info":{"title":"Nexus Payments API","version":"v1"},"tags":[{"name":"Financial Institutions","description":"Reference data for PSPs, FXPs, and SAPs, searchable by country, role, or institution ID."}],"servers":[{"url":"https://{environment}.payments.nexus.net","description":"Nexus participant-facing API endpoint. Resolved via Nexus private DNS over the established IPsec IKEv2 tunnel and not reachable from the public Internet.","variables":{"environment":{"default":"prod","enum":["pat","prod"],"description":"Deployment environment subdomain."}}}],"security":[{"mutualTLS":[],"nexusOAuth":["institutions.read"]}],"components":{"securitySchemes":{"mutualTLS":{"type":"mutualTLS","description":"Mutual TLS: the IPSO presents its X.509 client certificate on every connection, validated during the TLS handshake (fail-closed). The same certificate is the RFC 8705 binding anchor for the OAuth access token (see nexusOAuth)."}},"parameters":{"SignatureInputBodyless":{"name":"Signature-Input","in":"header","required":true,"description":"RFC 9421 signature metadata for a request without a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled `nexus` whose covered components are exactly `\"@method\" \"@authority\" \"@path\" \"@query\"`, followed by `\"if-none-match\"` when that header is sent. `@query` is always covered; an empty query serialises as `?`, so query parameters cannot be added or removed undetected. Signature parameters, emitted in this order: `created` and `expires` (Unix seconds; `expires` = `created` + 300; the receiver rejects `created` more than ±5 minutes from its clock or a signature past `expires`), `keyid` (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), `alg` (always `rsa-pss-sha512`) and `tag` (always `nexus-v1`). The signature parameters are signed through the `@signature-params` line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.","schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@method\" \"@authority\" \"@path\" \"@query\"( \"if-none-match\")?\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"Signature":{"name":"Signature","in":"header","required":true,"description":"RFC 9421 signature value: one dictionary member labelled `nexus` holding an RFC 8941 byte sequence - the **standard base64** (not base64url) RSASSA-PSS signature using SHA-512 (`rsa-pss-sha512`), computed over the RFC 9421 signature base built from the components and parameters declared in `Signature-Input`. Produced with the sender's own signing private key; the receiver verifies it against the sender's registered signing public key resolved from `keyid`. With the minimum RSA-3072 key the signature is 384 bytes, i.e. 512 base64 characters. A missing, malformed or non-verifying signature is rejected with AE005.","schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}}},"headers":{"ResponseSignatureInput":{"description":"RFC 9421 signature metadata for a GET response, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). Signed by the responding server with its own signing private key. Covered components: `\"@status\" \"content-type\" \"content-digest\"` on 200, or `\"@status\" \"etag\"` on 304, followed in both cases by the request-bound components `\"@method\";req \"@path\";req \"@query\";req`, which tie the response to the resource that was requested. Same `created`, `expires`, `keyid`, `alg` and `tag` rules as requests. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.","required":true,"schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@status\" (\"content-type\" \"content-digest\"|\"etag\") \"@method\";req \"@path\";req \"@query\";req\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"ResponseSignature":{"description":"RFC 9421 response signature: one dictionary member labelled `nexus` holding the standard base64 `rsa-pss-sha512` signature produced by the responding server over the signature base declared in the response `Signature-Input`. Verified by the client against the server's registered signing public key.","required":true,"schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}},"ResponseContentDigest":{"description":"RFC 9530 SHA-512 digest of the exact response body bytes, covered by the response signature.","required":true,"schema":{"type":"string","pattern":"^sha-512=:[A-Za-z0-9+/]{86}==:$"}}},"schemas":{"FinancialInstitutionResponse":{"type":"object","description":"Financial institution details.","properties":{"name":{"type":"string","description":"Financial institution name.","minLength":1,"maxLength":140},"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"]}}},"required":["countryCode","finInstId","name","roles"]},"FinancialInstitutionIdResponse":{"type":"object","description":"Financial institution identifiers.","properties":{"bicfi":{"type":["array","null"],"items":{"type":"string","description":"BICFI identifier.","maxLength":11,"pattern":"^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$"}},"lei":{"type":["string","null"],"description":"LEI identifier.","maxLength":20,"pattern":"^[0-9A-Z]{18}[0-9]{2}$"},"otherId":{"type":["array","null"],"description":"Other identifier values.","items":{"type":"string"}}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the Nexus authentication layer or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.\n\n#### Validation rules\n\n- All four fields are required and never `null`.\n- `statusCode`: always `RJCT`.\n- `reasonCode`: 5 characters matching `^[A-Z]{2}[0-9]{3}$`; family prefix `TE` (technical), `AE` (authentication/authorisation, enforced at authentication) or `BE` (business); one of the values enumerated in the `reasonCode` schema.\n- `name`: UPPER_SNAKE_CASE, 1–50 characters; the name paired with `reasonCode` (e.g. `TE001` ↔ `INVALID_REQUEST`).\n- `description`: 1–500 characters; MUST NOT contain PII.\n- 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,"minLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, AE001–AE006, enforced at authentication), BE (Business Error, BE001–BE031).","enum":["TE001","TE002","TE099","AE001","AE002","AE003","AE004","AE005","AE006","BE001","BE002","BE007","BE008","BE009","BE010","BE011","BE012","BE013","BE014","BE015","BE016","BE017","BE018","BE019","BE020","BE021","BE030","BE031"],"maxLength":5,"pattern":"^[A-Z]{2}[0-9]{3}$","minLength":5},"name":{"type":"string","description":"Machine-readable error name paired with the reason code.","maxLength":50,"pattern":"^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$","minLength":1},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII.","maxLength":500,"minLength":1}},"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.\n\n---\n\n#### Response validation rules\n\n**200 OK** — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\n\n| Field | Type | Presence | Nullable | Constraints |\n|---|---|---|---|---|\n| `name` | string | Required | N | min length 1; max length 140 |\n| `finInstId` | object | Required | N | — |\n| `finInstId.bicfi` | array | Conditional — present when the institution has a BIC | Y | each item: pattern `^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$`, max length 11 |\n| `finInstId.lei` | string | Optional | Y | pattern `^[0-9A-Z]{18}[0-9]{2}$`; max length 20 |\n| `finInstId.otherId` | array | Optional | Y | — |\n| `countryCode` | string | Required | N | pattern `^[A-Z]{2}$`; length 2 |\n| `roles` | array | Required | N | each item: one of `psp`, `fxp`, `sap` |\n\n**Cross-field rules**\n\n- `finInstId` contains the requested identifier under the requested `finInstIdType`.\n- `finInstId.lei` is `null` when no LEI is available; `finInstId.otherId` is an empty array when there are no other identifiers.\n\n**Response signature** — every 200 and 304 response carries `Signature-Input` and `Signature` (plus `Content-Digest` on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\n\n**Error responses (4xx/5xx with a body)** — the body MUST conform to `ErrorApiResponse`: `statusCode` = `RJCT`; `reasonCode` matches `^[A-Z]{2}[0-9]{3}$`; `name` is UPPER_SNAKE_CASE (≤ 50); `description` ≤ 500 characters and MUST NOT contain PII. `reasonCode` values for this operation: `TE001`, `BE019`, `BE020`, `TE099`, `AE001`, `AE002`, `AE003`, `AE005`, `AE006`, `AE004`. Gateway errors (405, 429, 502, 503, 504) carry no body.","operationId":"getFinancialInstitutionById","parameters":[{"name":"Accept","in":"header","description":"*/*","required":true,"schema":{"type":"string","default":"*/*"}},{"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).\n\nFormat depends on the sibling `finInstIdType` parameter: `BICFI` is 8 or 11 characters, `LEI` is 20 characters, `otherId` is free text of up to 35 characters. The per-type format is enforced as a business validation (`BE019 FI_ID_TYPE_UNSUPPORTED` / `BE020 FI_NOT_FOUND`) rather than by this schema, because it cannot be expressed as a constraint on an independent parameter.\n","required":true,"schema":{"type":"string","minLength":1,"maxLength":35}},{"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"}},{"$ref":"#/components/parameters/SignatureInputBodyless"},{"$ref":"#/components/parameters/Signature"}],"responses":{"200":{"description":"Financial institution retrieved.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}},"Cache-Control":{"description":"Caching guidance for this reference-data resource. Nexus invalidates the underlying cache immediately when the underlying configuration changes; responses may otherwise be cached for up to 300 seconds.","schema":{"type":"string"}},"Signature-Input":{"$ref":"#/components/headers/ResponseSignatureInput"},"Signature":{"$ref":"#/components/headers/ResponseSignature"},"Content-Digest":{"$ref":"#/components/headers/ResponseContentDigest"}},"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"}},"Signature-Input":{"$ref":"#/components/headers/ResponseSignatureInput"},"Signature":{"$ref":"#/components/headers/ResponseSignature"}}},"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 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.\
> \
> \---\
> \
> \#### Response validation rules\
> \
> \*\*200 OK\*\* — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\
> \
> The body is a top-level JSON array (no envelope); it may be empty unless stated otherwise.\
> \
> \| Field | Type | Presence | Nullable | Constraints |\
> \|---|---|---|---|---|\
> \| \`\[].name\` | string | Required | N | min length 1; max length 140 |\
> \| \`\[].finInstId\` | object | Required | N | — |\
> \| \`\[].finInstId.bicfi\` | array | Conditional — present when the institution has a BIC | Y | each item: pattern \`^\[A-Z]{6}\[0-9A-Z]{2}(\[0-9A-Z]{3})?$\`, max length 11 |\
> \| \`\[].finInstId.lei\` | string | Optional | Y | pattern \`^\[0-9A-Z]{18}\[0-9]{2}$\`; max length 20 |\
> \| \`\[].finInstId.otherId\` | array | Optional | Y | — |\
> \| \`\[].countryCode\` | string | Required | N | pattern \`^\[A-Z]{2}$\`; length 2 |\
> \| \`\[].roles\` | array | Required | N | each item: one of \`psp\`, \`fxp\`, \`sap\` |\
> \
> \*\*Cross-field rules\*\*\
> \
> \- Every item's \`countryCode\` equals the \`countryCode\` path parameter.\
> \- Every item's \`roles\` contains the requested \`finInstRole\` (all roles when \`finInstRole\` = \`any\`).\
> \- \`finInstId.lei\` is \`null\` when no LEI is available; \`finInstId.otherId\` is an empty array when there are no other identifiers.\
> \
> \*\*Response signature\*\* — every 200 and 304 response carries \`Signature-Input\` and \`Signature\` (plus \`Content-Digest\` on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\
> \
> \*\*Error responses (4xx/5xx with a body)\*\* — the body MUST conform to \`ErrorApiResponse\`: \`statusCode\` = \`RJCT\`; \`reasonCode\` matches \`^\[A-Z]{2}\[0-9]{3}$\`; \`name\` is UPPER\_SNAKE\_CASE (≤ 50); \`description\` ≤ 500 characters and MUST NOT contain PII. \`reasonCode\` values for this operation: \`TE001\`, \`BE017\`, \`BE016\`, \`BE018\`, \`TE099\`, \`AE001\`, \`AE002\`, \`AE003\`, \`AE005\`, \`AE006\`, \`AE004\`. Gateway errors (405, 429, 502, 503, 504) carry no body.

```json
{"openapi":"3.1.0","info":{"title":"Nexus Payments API","version":"v1"},"tags":[{"name":"Financial Institutions","description":"Reference data for PSPs, FXPs, and SAPs, searchable by country, role, or institution ID."}],"servers":[{"url":"https://{environment}.payments.nexus.net","description":"Nexus participant-facing API endpoint. Resolved via Nexus private DNS over the established IPsec IKEv2 tunnel and not reachable from the public Internet.","variables":{"environment":{"default":"prod","enum":["pat","prod"],"description":"Deployment environment subdomain."}}}],"security":[{"mutualTLS":[],"nexusOAuth":["institutions.read"]}],"components":{"securitySchemes":{"mutualTLS":{"type":"mutualTLS","description":"Mutual TLS: the IPSO presents its X.509 client certificate on every connection, validated during the TLS handshake (fail-closed). The same certificate is the RFC 8705 binding anchor for the OAuth access token (see nexusOAuth)."}},"parameters":{"SignatureInputBodyless":{"name":"Signature-Input","in":"header","required":true,"description":"RFC 9421 signature metadata for a request without a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled `nexus` whose covered components are exactly `\"@method\" \"@authority\" \"@path\" \"@query\"`, followed by `\"if-none-match\"` when that header is sent. `@query` is always covered; an empty query serialises as `?`, so query parameters cannot be added or removed undetected. Signature parameters, emitted in this order: `created` and `expires` (Unix seconds; `expires` = `created` + 300; the receiver rejects `created` more than ±5 minutes from its clock or a signature past `expires`), `keyid` (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), `alg` (always `rsa-pss-sha512`) and `tag` (always `nexus-v1`). The signature parameters are signed through the `@signature-params` line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.","schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@method\" \"@authority\" \"@path\" \"@query\"( \"if-none-match\")?\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"Signature":{"name":"Signature","in":"header","required":true,"description":"RFC 9421 signature value: one dictionary member labelled `nexus` holding an RFC 8941 byte sequence - the **standard base64** (not base64url) RSASSA-PSS signature using SHA-512 (`rsa-pss-sha512`), computed over the RFC 9421 signature base built from the components and parameters declared in `Signature-Input`. Produced with the sender's own signing private key; the receiver verifies it against the sender's registered signing public key resolved from `keyid`. With the minimum RSA-3072 key the signature is 384 bytes, i.e. 512 base64 characters. A missing, malformed or non-verifying signature is rejected with AE005.","schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}}},"headers":{"ResponseSignatureInput":{"description":"RFC 9421 signature metadata for a GET response, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). Signed by the responding server with its own signing private key. Covered components: `\"@status\" \"content-type\" \"content-digest\"` on 200, or `\"@status\" \"etag\"` on 304, followed in both cases by the request-bound components `\"@method\";req \"@path\";req \"@query\";req`, which tie the response to the resource that was requested. Same `created`, `expires`, `keyid`, `alg` and `tag` rules as requests. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.","required":true,"schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@status\" (\"content-type\" \"content-digest\"|\"etag\") \"@method\";req \"@path\";req \"@query\";req\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"ResponseSignature":{"description":"RFC 9421 response signature: one dictionary member labelled `nexus` holding the standard base64 `rsa-pss-sha512` signature produced by the responding server over the signature base declared in the response `Signature-Input`. Verified by the client against the server's registered signing public key.","required":true,"schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}},"ResponseContentDigest":{"description":"RFC 9530 SHA-512 digest of the exact response body bytes, covered by the response signature.","required":true,"schema":{"type":"string","pattern":"^sha-512=:[A-Za-z0-9+/]{86}==:$"}}},"schemas":{"FinancialInstitutionResponse":{"type":"object","description":"Financial institution details.","properties":{"name":{"type":"string","description":"Financial institution name.","minLength":1,"maxLength":140},"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"]}}},"required":["countryCode","finInstId","name","roles"]},"FinancialInstitutionIdResponse":{"type":"object","description":"Financial institution identifiers.","properties":{"bicfi":{"type":["array","null"],"items":{"type":"string","description":"BICFI identifier.","maxLength":11,"pattern":"^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$"}},"lei":{"type":["string","null"],"description":"LEI identifier.","maxLength":20,"pattern":"^[0-9A-Z]{18}[0-9]{2}$"},"otherId":{"type":["array","null"],"description":"Other identifier values.","items":{"type":"string"}}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the Nexus authentication layer or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.\n\n#### Validation rules\n\n- All four fields are required and never `null`.\n- `statusCode`: always `RJCT`.\n- `reasonCode`: 5 characters matching `^[A-Z]{2}[0-9]{3}$`; family prefix `TE` (technical), `AE` (authentication/authorisation, enforced at authentication) or `BE` (business); one of the values enumerated in the `reasonCode` schema.\n- `name`: UPPER_SNAKE_CASE, 1–50 characters; the name paired with `reasonCode` (e.g. `TE001` ↔ `INVALID_REQUEST`).\n- `description`: 1–500 characters; MUST NOT contain PII.\n- 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,"minLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, AE001–AE006, enforced at authentication), BE (Business Error, BE001–BE031).","enum":["TE001","TE002","TE099","AE001","AE002","AE003","AE004","AE005","AE006","BE001","BE002","BE007","BE008","BE009","BE010","BE011","BE012","BE013","BE014","BE015","BE016","BE017","BE018","BE019","BE020","BE021","BE030","BE031"],"maxLength":5,"pattern":"^[A-Z]{2}[0-9]{3}$","minLength":5},"name":{"type":"string","description":"Machine-readable error name paired with the reason code.","maxLength":50,"pattern":"^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$","minLength":1},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII.","maxLength":500,"minLength":1}},"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.\n\n---\n\n#### Response validation rules\n\n**200 OK** — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\n\nThe body is a top-level JSON array (no envelope); it may be empty unless stated otherwise.\n\n| Field | Type | Presence | Nullable | Constraints |\n|---|---|---|---|---|\n| `[].name` | string | Required | N | min length 1; max length 140 |\n| `[].finInstId` | object | Required | N | — |\n| `[].finInstId.bicfi` | array | Conditional — present when the institution has a BIC | Y | each item: pattern `^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?$`, max length 11 |\n| `[].finInstId.lei` | string | Optional | Y | pattern `^[0-9A-Z]{18}[0-9]{2}$`; max length 20 |\n| `[].finInstId.otherId` | array | Optional | Y | — |\n| `[].countryCode` | string | Required | N | pattern `^[A-Z]{2}$`; length 2 |\n| `[].roles` | array | Required | N | each item: one of `psp`, `fxp`, `sap` |\n\n**Cross-field rules**\n\n- Every item's `countryCode` equals the `countryCode` path parameter.\n- Every item's `roles` contains the requested `finInstRole` (all roles when `finInstRole` = `any`).\n- `finInstId.lei` is `null` when no LEI is available; `finInstId.otherId` is an empty array when there are no other identifiers.\n\n**Response signature** — every 200 and 304 response carries `Signature-Input` and `Signature` (plus `Content-Digest` on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\n\n**Error responses (4xx/5xx with a body)** — the body MUST conform to `ErrorApiResponse`: `statusCode` = `RJCT`; `reasonCode` matches `^[A-Z]{2}[0-9]{3}$`; `name` is UPPER_SNAKE_CASE (≤ 50); `description` ≤ 500 characters and MUST NOT contain PII. `reasonCode` values for this operation: `TE001`, `BE017`, `BE016`, `BE018`, `TE099`, `AE001`, `AE002`, `AE003`, `AE005`, `AE006`, `AE004`. Gateway errors (405, 429, 502, 503, 504) carry no body.","operationId":"listFinancialInstitutionsByCountryAndRole","parameters":[{"name":"Accept","in":"header","description":"*/*","required":true,"schema":{"type":"string","default":"*/*"}},{"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"}},{"$ref":"#/components/parameters/SignatureInputBodyless"},{"$ref":"#/components/parameters/Signature"}],"responses":{"200":{"description":"Financial institutions retrieved.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}},"Cache-Control":{"description":"Caching guidance for this reference-data resource. Nexus invalidates the underlying cache immediately when the underlying configuration changes; responses may otherwise be cached for up to 300 seconds.","schema":{"type":"string"}},"Signature-Input":{"$ref":"#/components/headers/ResponseSignatureInput"},"Signature":{"$ref":"#/components/headers/ResponseSignature"},"Content-Digest":{"$ref":"#/components/headers/ResponseContentDigest"}},"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"}},"Signature-Input":{"$ref":"#/components/headers/ResponseSignatureInput"},"Signature":{"$ref":"#/components/headers/ResponseSignature"}}},"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."}}}}}}
```