Using with Account Id

An account ID (ACCT) only specifies the account, not the financial institution that holds that account. Therefore when the ACCT address type is selected, the Account Identification must always be used in conjunction with one of the Financial Institution Identification types in the table below.

Using with a Proxy

TABLE: Financial Institution Identification Types

The following Financial Institution Identification types are defined in ISO 20022.

In Nexus, each address type is defined by an ISO 20022 code:

• Account details will be described with the code IBAN (for IBAN) or ACCT (for Account Identifications).

• If ACCT is used, it will be necessary to also collect a Financial Institution Identification alongside the Account Identification. The Address Inputs API informs PSPs what information that needs to be collected.

• Proxies are defined by the ISO 20022 ExternalProxyAccountType1Code, taken from the ISO 20022 External Code Set

The table below lists the possible address type codes in Nexus. The most commonly accepted address types are bolded.

Table: Address types & codes

Nexus provides an API operation that returns a list of PSPs in a specific country along with their corresponding Financial Institution Identifications:

GET /countries/{countryCode}/fin-insts/psps

This can be used to generate a drop-down <select> menu item that allows the user to select the name of the PSP rather than entering the BIC manually.

This is useful for countries (such as the Philippines) that require the financial institution to be identified when using a proxy, or for countries (such as Singapore) where the convention is for the Recipient to share the full name of their PSP rather than the BIC.

In Nexus, each address type includes one or more address inputs. For example:

• An IBAN has only one address input (the IBAN field), because the IBAN itself combines information about the country, Financial Institution Id and Account Id.

• An ACCT will require two inputs: the Account Identification itself, plus a Financial Institution Identification such as a BIC (BICFI) or non-BIC Clearing System Member Id, such as sort code, routing number etc.

• A proxy normally requires only one input – the proxy identifier (such as a mobile phone number)

The Nexus APIs provide a list of the address inputs in a format that can be used by a PSP’s client application to dynamically generate the addressing form. Each input is defined in terms that are agnostic to programming frameworks (eg they are similar to common HTML attribute definitions), as shown in the table below.

The Nexus APIs also return some “hidden” inputs such as the account type code. These are fixed (ie not set by the Sender) and inform the Source PSP’s app how the address type should be processed. In some cases, the hidden information must be included in the acmt.023 message (such as the address type code when a proxy is used).

TABLE: Address Input structure

Nexus maintains a record of the address types (such as IBAN, Account Identifications or proxies) available in each country in the network, and the specific input fields that are required for each address type.

This information is initially provided by the IPSO or PDO in that country, at the point at which they are onboarded to Nexus. The information is then provided to PSPs through the Nexus APIs.

The data model for address types and inputs is described below, followed by examples.

Address inputs

In Nexus, each address type includes one or more address inputs. For example:

• An IBAN has only one address input (the IBAN field), because the IBAN itself combines information about the country, Financial Institution Id and Account Id.

• An ACCT will require two inputs: the Account Identification itself, plus a Financial Institution Identification such as a BIC (BICFI) or non-BIC Clearing System Member Id, such as sort code, routing number etc.

• A proxy normally requires only one input – the proxy identifier (such as a mobile phone number)

The Nexus APIs provide a list of the address inputs in a format that can be used by a PSP’s client application to dynamically generate the addressing form. Each input is defined in terms that are agnostic to programming frameworks (eg they are similar to common HTML attribute definitions), as shown in the table below.

The Nexus APIs also return some “hidden” inputs such as the account/proxy type code. These are fixed (ie not set by the Sender) and inform the Source PSP’s app how the address type should be processed. In some cases, the hidden information must be included in the acmt.023 message (such as the proxy type code when a proxy is used).

TABLE: Address Input structure

Example address types

Below is an example description of the address types for Indonesia. Please note the following:

• “id” would be automatically generated by the database. (In this example, human-readable IDs are given based on the country code and address type.)

• “code” defines the address type code

• “displayOrder” describes the order in which the proxy scheme recommends listing the address types when they are shown to the Sender (typically with mobile first, as the most common and user-friendly proxy type and the more obscure proxy types at the end of the list)

• For the ACCT address types “clearingSystemId” links to the internal Nexus ID of the instant payment system which accepts that address type

• For proxy address types, ”proxyDirectoryId” links to the ID of the proxy scheme that a proxy type belongs to.

Example address inputs

Below are three example descriptions of the address types. Firstly for a mobile phone proxy registered in Singapore, secondly for a Singaporean Account Identification, and third, for an IBAN registered in the UK.

Example mobile proxy

Note there are two inputs for a mobile proxy:

• The first is the text input field where the Sender will provide the mobile number of the Recipient. (This input starts with the “{“ prior to the first “attributes:”).

• The second is a hidden field which includes the MBNO address type (and proxy type) code. This addressTypeCode information will be required by the PSP to prepare the acmt.023 proxy resolution request.

Example account Identification

Note that there are three inputs for an Account Identification:

• The first input is the text input field where the Sender can input the Account Identification (accountOrProxyId)

• The second input is the text input where the Sender can input the Financial Institution Id (finInstId)

• The third is a hidden field which includes the code of the address type (“addressTypeCode”), which in this case is ACCC.

Example IBAN

For IBAN, only one text input is required, plus the hidden field addressTypeCode set to “IBAN”. The following example is for an IBAN to the United Kingdom.

List of PSPs

Nexus provides an API operation that returns a list of PSPs in a specific country along with their corresponding BICs:

GET /countries/{countryCode}/psps

This can be used to generate a drop-down <select> menu item that allows the user to select the name of the PSP rather than entering the BIC manually.

This is useful for countries (such as the Philippines) that require the financial institution to be identified when using a proxy, or for countries (such as Singapore) where the convention is for the Recipient to share the full name of their PSP rather than the BIC.

For usability, PSP app developers should enable the type-ahead feature that allows the user to start typing the PSP name to filter the list.

Masking of names

• The Recipient’s full name must be shared in full (unmasked) with the Source PSP to support sanctions screening. This information should be provided in the IdVrfctnReq/Rpt/UpdtdPtyAndAcctId/Pty/Nm element of the acmt.024 message.

• The Destination PSP may also share a ‘display name’, which could be the full name (unmasked) or the full name partially masked. This should be provided in the IdVrfctnReq/Rpt/UpdtdPtyAndAcctId/Acct/Nm element of the acmt.024 message.

• The Destination PSP is responsible for masking the name according to their own privacy and data protection preferences, policies or local regulations. Nexus will not mask or alter the information provided in the IdVrfctnReq/Rpt/UpdtdPtyAndAcctId/Acct/Nm element of the acmt.024 message.

Address types

Below is an example description of the address types for Indonesia. Please note the following:

• id would be automatically generated by the database. (In this example, human-readable IDs are given based on the country code and address type.)

• code defines the address type code

• displayOrder describes the order in which the relevant Proxy Directory Operator (PDO) recommends listing the address types when they are shown to the Sender

  • Typically mobile phone number would be listed first, as it is the most common and user-friendly proxy type and the more obscure proxy types at the end of the list)

• For the ACCT address types, “clearingSystemId” links to the ISO 20022 External Clearing System Identification Code of the instant payment system which accepts that address type. (Example values are given below.)

• For proxy address types, ”proxyDirectoryId” links to the ID of the proxy scheme that a proxy type belongs to.

Example address inputs

Below are three example descriptions of the address types. Firstly for a mobile phone proxy registered in Singapore, secondly for a Singaporean Account Identification, and third, for an IBAN registered in the UK.

Example mobile proxy

Note there are two inputs for a mobile proxy:

• The first is the text input field where the Sender will provide the mobile number of the Recipient. (This input starts with the “{“ prior to the first “attributes:”).

Account Identification

Note that there are three inputs for an Account Identification:

• The first input is the text input field where the Sender can input the Account Identification (accountOrProxyId)

• The second input is the text input where the Sender can input the Financial Institution Identification (finInstId)

• The third is a hidden field which includes the code of the address type (“addressTypeCode”), which in this case is ACCC.

Example IBAN

For IBAN, only one text input is required, plus the hidden field addressTypeCode set to “IBAN”. The following example is for an IBAN to the United Kingdom (GB).