Address Types & Inputs

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.

CODE (ISO 20022)	Meaning	Type	Notes
BICFI	Business Identifier Code for Financial Institution	Financial Institution Id	Used in conjunction with an Account Identifier (and in some countries, with the proxy)
LEI	Legal Entity Identifier	Financial Institution Id	We are not aware of any IPS that uses LEIs to address payments, but the ISO 20022 messages can support use of LEI.
ClrSysMmbId	(Non-BIC) Clearing System Member Id	Financial Institution Id	Used in conjunction with an Account Identifier. Maps to ISO 20022 element Financial Institution Identification > Clearing System Member Identification > Member Id

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)

In some cases, such as the Philippines, a Financial Institution Identification must also be provided for each proxy (as the same proxy may be registered to multiple financial institutions in the Philippines).

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

ELEMENT	SUB ELEMENT	FORMAT	USAGE
Label	Code	Text	Same as the Address Type code or Financial Institution Identification Type code above. E.g. IBAN, ACCT or a proxy type code like MBNO. This code can be mapped to the app user’s language.
	Title	Key-value pair, where key is the 2-letter language code (eg “en”) and the value is the explanatory title	Further description that can be used to guide the Sender, to be used in a tooltip or explanatory text below the input form. A description in English (“en”) should always be provided. PDOs may choose to add additional languages based on the likely language of Senders to that country. (For example, countries may wish to add the languages of their closest trading partners and remittance corridors.) For example, for a proxy type NIDN (National Identify Number) for Singapore, the description may be “NRIC/FIN” – two national identity number types)
Attributes	Name	ENUM: accountIdOrProxyId, addressTypeCode, finInstId	Suggested name of the form element that takes the input from the Sender. (Note: addressTypeCode would be a hidden input that is not visible to the Sender.) Note: this is NOT the name of the input type that should be shown to the Sender – for that, see Label.Code
	Type	Valid HTML input “type” attribute	Describes the type of HTML input element, eg text, tel, number, email
	Pattern	Regular expression	Used to validate the form. (For email, this should be null, relying on the browser or app’s default email validation instead.)
	Placeholder	Text	An example value that can optionally be shown in the input element before the Sender begins to enter information
	Required	true/false	Whether this input is required or optional. (Currently all inputs are set to required. Optional inputs may be used in cases where a comparison model of account resolution is used, in which the Sender can optionally provide information about the Recipient that would be compared by the Destination PSP against their own verified records.)
ISO 20022 Path	(Code of the message type without the dot e.g. “acmt024”)	Text	The XPath to the position in an ISO 20022 message where this information can be used. Multiple message types may be specified, depending on whether proxy resolution is required first, or whether the input can be used directly in the pacs.008 payment instruction. NB: The message name is defined without the period/dot character “.”, because the dot character is used in JavaScript to refer to properties of a JSON object (eg “attributes.name”).

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.

{
  "addressTypes": [
    {
      "id": "IDACCT",
      "countries": [
        "ID"
      ],
      "code": "ACCT",
      "clearingSystemId": "IDRBFAST",
      "displayOrder": 3
    },
    {
      "id": "IDEMAL",
      "countries": [
        "ID"
      ],
      "code": "EMAL",
      "proxyDirectoryId": "IDPROXY",
      "displayOrder": 2
    },
    {
      "id": "IDMBNO",
      "countries": [
        "ID"
      ],
      "code": "MBNO",
      "proxyDirectoryId": "IDPROXY",
      "displayOrder": 1
    }
  ]
}

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.

{
  "id": "SGMBNO",
  "inputs": [
    {
      "attributes": {
        "name": "accountOrProxyId",
        "type": "tel",
        "pattern": "^\\+(?:[0-9] ?){6,14}[0-9]$",
        "placeholder": "[phone]",
        "required": true
      },
      "iso20022Path": {
        "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Prxy/Id",
        "pacs008": null
      },
      "label": {
        "code": "MBNO",
        "title": {
          "en": "Mobile phone number, including the country code",
          "de": "Mobiltelefonnummer, einschließlich der Landesvorwahl"
        }
      }
    },
    {
      "attributes": {
        "name": "addressTypeCode",
        "type": "hidden",
        "value": "MBNO",
        "required": true
      },
      "iso20022Path": {
        "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Prxy/Tp/Cd",
        "pacs008": null
      }
    }
  ]
}

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.

{
  "id": "SGACCT",
  "inputs": [
    {
      "attributes": {
        "name": "accountOrProxyId",
        "type": "number",
        "pattern": "^\\+\\d{9,10}$",
        "placeholder": "1234567890",
        "required": true
      },
      "iso20022Path": {
        "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Id/Othr/Id",
        "pacs008": "/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CrtrAcct/Id/Othr/Id"
      },
      "label": {
        "code": "ACCT",
        "title": {
          "en": "Account number, 9-10 digits",
          "de": "Kontonummer, 9-10 Ziffern"
        }
      }
    },
    {
      "attributes": {
        "name": "finInstId",
        "type": "text",
        "pattern": "^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?",
        "placeholder": "AAAASGAA OR AAAASGAA123",
        "required": true
      },
      "iso20022Path": {
        "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Agt/FinInstnId/BICFI",
        "pacs008": "/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CdtrAgt/FinInstnId/BICFI"
      },
      "label": {
        "code": "BICFI",
        "title": {
          "en": "BIC of the Creditor's Bank or Payment Service Provider",
          "de": "BIC der Kreditorbank des Payment Service Providers"
        }
      }
    },
    {
      "attributes": {
        "name": "addressTypeCode",
        "type": "hidden",
        "value": "ACCT",
        "required": true
      },
      "iso20022Path": {
        "acmt023": null,
        "pacs008": null
      }
    }
  ]
}

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.

{
  "id": "GBIBAN",
  "inputs": [
    {
      "attributes": {
        "name": "accountOrProxyId",
        "type": "number",
        "pattern": "^GB[0-9]{2}[A-Z]{4}[0-9]{14}$",
        "placeholder": "GB29 NWBK 6016 1331 9268 19",
        "required": true
      },
      "iso20022Path": {
        "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Id/IBAN",
        "pacs008": "/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CrtrAcct/Id/IBAN"
      },
      "label": {
        "code": "IBAN",
        "title": [
          {
            "en": "International Bank Account Number",
            "de": "Internationale Bankkontonummer"
          }
        ]
      }
    },
    {
      "attributes": {
        "name": "addressTypeCode",
        "type": "hidden",
        "value": "IBAN",
        "required": true
      },
      "iso20022Path": {
        "acmt023": null,
        "pacs008": null
      }
    }
  ]
}

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.