Financial Institutions

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

Get Financial Institutions by Role

get

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.

Required scopes

This endpoint requires the following scopes:

• : Read the financial institution directory

Authorizations

mutualTLS

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).

OAuth2clientCredentialsRequired

OAuth2 client-credentials access token issued per participant, presented as Authorization: Bearer <token>. Tokens are certificate-bound per RFC 8705: the token carries a cnf."x5t#S256" confirmation claim recording the SHA-256 thumbprint of the IPSO's mTLS client certificate, and the request is rejected (AE006) when the certificate presented on the connection does not match that thumbprint.

Token URL:

Path parameters

finInstRolestring · enumRequired

One of psp, fxp, sap, any. Defaults to any if blank.

Example: anyPossible values:

Query parameters

cursorstringOptional

Opaque cursor for the next page ordered by country code and name.

Example: eyJjb3VudHJ5Q29kZSI6IlRIIiwibmFtZSI6IkZYUC1BIn0

limitintegerOptional

Number of results per page.

Default: 20Example: 20

Header parameters

AcceptstringRequired

/

Default: */*Example: */*

Responses

200

Success.

application/json

Cursor-paged response of financial institutions.

nextCursorstringOptional

Cursor for the next page.

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/fin-insts/{finInstRole}

GET /v1/fin-insts/{finInstRole} HTTP/1.1
Host: prod.payments.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "finInsts": [
    {
      "name": "Bank Central Asia",
      "finInstId": {
        "bicfi": [
          "BBBUIDJA"
        ],
        "lei": null,
        "otherId": null
      },
      "countryCode": "ID",
      "roles": [
        "psp",
        "sap"
      ]
    },
    {
      "name": "Bank of the Philippine Islands",
      "finInstId": {
        "bicfi": [
          "BOPIPHMM"
        ],
        "lei": null,
        "otherId": null
      },
      "countryCode": "PH",
      "roles": [
        "psp"
      ]
    },
    {
      "name": "DBS Bank Ltd",
      "finInstId": {
        "bicfi": [
          "DBSSSGSG"
        ],
        "lei": "ATUEL7OJR5057F2PV266",
        "otherId": []
      },
      "countryCode": "SG",
      "roles": [
        "psp",
        "fxp"
      ]
    },
    {
      "name": "United Overseas Bank Limited",
      "finInstId": {
        "bicfi": [
          "UOVBSGSG"
        ],
        "lei": "AR3L4Z0XCMCQS27SE236",
        "otherId": []
      },
      "countryCode": "SG",
      "roles": [
        "psp"
      ]
    },
    {
      "name": "FXP-A",
      "finInstId": {
        "bicfi": [
          "STNXGBAA"
        ],
        "lei": null,
        "otherId": null
      },
      "countryCode": "TH",
      "roles": [
        "fxp"
      ]
    },
    {
      "name": "Kasikornbank Public Company Limited",
      "finInstId": {
        "bicfi": [
          "KASITHBK"
        ],
        "lei": null,
        "otherId": null
      },
      "countryCode": "TH",
      "roles": [
        "psp",
        "fxp",
        "sap"
      ]
    }
  ],
  "nextCursor": null
}

Get Financial Institution by Financial Institution ID

get

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.

Required scopes

This endpoint requires the following scopes:

• : Read the financial institution directory

Authorizations

mutualTLS

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).

OAuth2clientCredentialsRequired

OAuth2 client-credentials access token issued per participant, presented as Authorization: Bearer <token>. Tokens are certificate-bound per RFC 8705: the token carries a cnf."x5t#S256" confirmation claim recording the SHA-256 thumbprint of the IPSO's mTLS client certificate, and the request is rejected (AE006) when the certificate presented on the connection does not match that thumbprint.

Token URL:

Path parameters

finInstIdTypestring · enumRequired

BICFI, LEI, otherId.

Example: BICFIPossible values:

finInstIdstring · min: 1 · max: 35Required

Identifier value (format validated per type).

Format 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.

Example: DBSSSGSG

Header parameters

AcceptstringRequired

/

Default: */*Example: */*

If-None-MatchstringOptional

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.

Example: "a1b2c3"

Responses

200

Financial institution retrieved.

application/json

304

Not Modified. The resource has not changed since the last request.

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

404

Resource Not Found

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/fin-insts/any/{finInstIdType}/{finInstId}

GET /v1/fin-insts/any/{finInstIdType}/{finInstId} HTTP/1.1
Host: prod.payments.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "name": "DBS Bank Ltd",
  "finInstId": {
    "BICFI": [
      "DBSSSGSG"
    ],
    "LEI": "ATUEL7OJR5057F2PV266",
    "otherId": []
  },
  "countryCode": "SG",
  "roles": [
    "psp",
    "sap"
  ]
}

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

get

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.

Required scopes

This endpoint requires the following scopes:

• : Read the financial institution directory

Authorizations

mutualTLS

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).

OAuth2clientCredentialsRequired

OAuth2 client-credentials access token issued per participant, presented as Authorization: Bearer <token>. Tokens are certificate-bound per RFC 8705: the token carries a cnf."x5t#S256" confirmation claim recording the SHA-256 thumbprint of the IPSO's mTLS client certificate, and the request is rejected (AE006) when the certificate presented on the connection does not match that thumbprint.

Token URL:

Path parameters

countryCodestring · min: 2 · max: 2Required

ISO 3166-1 alpha-2 (e.g., SG).

Example: SGPattern: ^[A-Z]{2}$

finInstRolestring · enumRequired

psp, fxp, sap, any (optional, defaults any).

Example: pspPossible values:

Header parameters

AcceptstringRequired

/

Default: */*Example: */*

If-None-MatchstringOptional

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.

Example: "a1b2c3"

Responses

200

Financial institutions retrieved.

application/json

304

Not Modified. The resource has not changed since the last request.

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

404

Resource Not Found

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/countries/{countryCode}/fin-insts/{finInstRole}

GET /v1/countries/{countryCode}/fin-insts/{finInstRole} HTTP/1.1
Host: prod.payments.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "name": "DBS Bank Ltd",
    "finInstId": {
      "bicfi": [
        "DBSSSGSG"
      ],
      "lei": "ATUEL7OJR5057F2PV266",
      "otherId": []
    },
    "countryCode": "SG",
    "roles": [
      "psp",
      "sap"
    ]
  },
  {
    "name": "United Overseas Bank Limited",
    "finInstId": {
      "bicfi": [
        "UOVBSGSG"
      ],
      "lei": "AR3L4Z0XCMCQS27SE236",
      "otherId": []
    },
    "countryCode": "SG",
    "roles": [
      "psp"
    ]
  }
]