# Table of Contents - [Nexus Overview | Nexus Payments Docs](#nexus-overview-nexus-payments-docs) - [How to use this site | Nexus Payments Docs](#how-to-use-this-site-nexus-payments-docs) - [Scope of Nexus payments | Nexus Payments Docs](#scope-of-nexus-payments-nexus-payments-docs) - [Steps 1-2: Country, Currency & Amount | Nexus Payments Docs](#steps-1-2-country-currency-amount-nexus-payments-docs) - [Step 12: Ask the Sender for approval | Nexus Payments Docs](#step-12-ask-the-sender-for-approval-nexus-payments-docs) - [Key Points | Nexus Payments Docs](#key-points-nexus-payments-docs) - [Terminology | Nexus Payments Docs](#terminology-nexus-payments-docs) - [Steps 3-6: Exchange Rates | Nexus Payments Docs](#steps-3-6-exchange-rates-nexus-payments-docs) - [Step 17: Accept the confirmation and notify Sender | Nexus Payments Docs](#step-17-accept-the-confirmation-and-notify-sender-nexus-payments-docs) - [Step 13-16: Set up and send the payment instruction | Nexus Payments Docs](#step-13-16-set-up-and-send-the-payment-instruction-nexus-payments-docs) - [Steps 10-11: Sanctions screening | Nexus Payments Docs](#steps-10-11-sanctions-screening-nexus-payments-docs) - [Steps 7-9: Addressing, Proxy Resolution & Confirmation of Payee | Nexus Payments Docs](#steps-7-9-addressing-proxy-resolution-confirmation-of-payee-nexus-payments-docs) - [Overview of Payment Addressing in Nexus | Nexus Payments Docs](#overview-of-payment-addressing-in-nexus-nexus-payments-docs) - [Addressing via Proxies (Aliases) | Nexus Payments Docs](#addressing-via-proxies-aliases-nexus-payments-docs) - [Addressing via Account Details | Nexus Payments Docs](#addressing-via-account-details-nexus-payments-docs) - [Key Points | Nexus Payments Docs](#key-points-nexus-payments-docs) - [List of PSPs | Nexus Payments Docs](#list-of-psps-nexus-payments-docs) - [Financial Institution Identification | Nexus Payments Docs](#financial-institution-identification-nexus-payments-docs) - [Obligations of PSPs using the Proxy Directory | Nexus Payments Docs](#obligations-of-psps-using-the-proxy-directory-nexus-payments-docs) - [Address Inputs | Nexus Payments Docs](#address-inputs-nexus-payments-docs) - [Obligations on the Proxy Directory Operator | Nexus Payments Docs](#obligations-on-the-proxy-directory-operator-nexus-payments-docs) - [Role of the Proxy Directory Operator (PDO) | Nexus Payments Docs](#role-of-the-proxy-directory-operator-pdo-nexus-payments-docs) - [Masking of Display Names | Nexus Payments Docs](#masking-of-display-names-nexus-payments-docs) - [Step 4: Source PSP processes the results | Nexus Payments Docs](#step-4-source-psp-processes-the-results-nexus-payments-docs) - [Address Types | Nexus Payments Docs](#address-types-nexus-payments-docs) - [Proxy & Account Resolution Process | Nexus Payments Docs](#proxy-account-resolution-process-nexus-payments-docs) - [Onboarding a Proxy Directory Operator onto Nexus | Nexus Payments Docs](#onboarding-a-proxy-directory-operator-onto-nexus-nexus-payments-docs) - [Step 2: Proxy Resolution Messaging Sequence | Nexus Payments Docs](#step-2-proxy-resolution-messaging-sequence-nexus-payments-docs) - [Step 1: Sender inputs proxy or account details | Nexus Payments Docs](#step-1-sender-inputs-proxy-or-account-details-nexus-payments-docs) - [Step 3: Account Resolution Messaging Sequence | Nexus Payments Docs](#step-3-account-resolution-messaging-sequence-nexus-payments-docs) - [Obligations & Compliance | Nexus Payments Docs](#obligations-compliance-nexus-payments-docs) - [Revenue model for FXPs | Nexus Payments Docs](#revenue-model-for-fxps-nexus-payments-docs) - [Examples | Nexus Payments Docs](#examples-nexus-payments-docs) - [Address Types & Inputs | Nexus Payments Docs](#address-types-inputs-nexus-payments-docs) - [Joining Nexus as a third-party FXP | Nexus Payments Docs](#joining-nexus-as-a-third-party-fxp-nexus-payments-docs) - [Key Points | Nexus Payments Docs](#key-points-nexus-payments-docs) - [Role of the FX Provider | Nexus Payments Docs](#role-of-the-fx-provider-nexus-payments-docs) - [Improving rates for specific PSPs | Nexus Payments Docs](#improving-rates-for-specific-psps-nexus-payments-docs) - [Maximum value of a Nexus payment | Nexus Payments Docs](#maximum-value-of-a-nexus-payment-nexus-payments-docs) - [Accessing Instant Payment Systems | Nexus Payments Docs](#accessing-instant-payment-systems-nexus-payments-docs) - [Accounts & Relationships | Nexus Payments Docs](#accounts-relationships-nexus-payments-docs) - [Improving rates for larger transactions | Nexus Payments Docs](#improving-rates-for-larger-transactions-nexus-payments-docs) - [Managing Liquidity | Nexus Payments Docs](#managing-liquidity-nexus-payments-docs) - [High priority vs normal priority payments | Nexus Payments Docs](#high-priority-vs-normal-priority-payments-nexus-payments-docs) - [Onboarding PSPs | Nexus Payments Docs](#onboarding-psps-nexus-payments-docs) - [How Third-Party FX provision works in Nexus | Nexus Payments Docs](#how-third-party-fx-provision-works-in-nexus-nexus-payments-docs) - [Annex: Sponsoring PSPs and Sponsored Entities | Nexus Payments Docs](#annex-sponsoring-psps-and-sponsored-entities-nexus-payments-docs) - [Annex: 4-step vs 5-step Processes in Domestic Clearing and Settlement | Nexus Payments Docs](#annex-4-step-vs-5-step-processes-in-domestic-clearing-and-settlement-nexus-payments-docs) - [Booking flow for Source PSPs | Nexus Payments Docs](#booking-flow-for-source-psps-nexus-payments-docs) - [Special Scenarios | Nexus Payments Docs](#special-scenarios-nexus-payments-docs) - [Costs and Revenue for SAPs | Nexus Payments Docs](#costs-and-revenue-for-saps-nexus-payments-docs) - [Message transformation by Nexus | Nexus Payments Docs](#message-transformation-by-nexus-nexus-payments-docs) - [Payment setup for PSPs who provide their own FX | Nexus Payments Docs](#payment-setup-for-psps-who-provide-their-own-fx-nexus-payments-docs) - [Key Points | Nexus Payments Docs](#key-points-nexus-payments-docs) - [Role of the Settlement Access Provider (SAP) | Nexus Payments Docs](#role-of-the-settlement-access-provider-sap-nexus-payments-docs) - [Payment Flow | Nexus Payments Docs](#payment-flow-nexus-payments-docs) - [Rates from Third-Party FX Providers | Nexus Payments Docs](#rates-from-third-party-fx-providers-nexus-payments-docs) - [Key Points | Nexus Payments Docs](#key-points-nexus-payments-docs) - [Ensuring settlement certainty | Nexus Payments Docs](#ensuring-settlement-certainty-nexus-payments-docs) - [Message Guidelines (Excel) | Nexus Payments Docs](#message-guidelines-excel-nexus-payments-docs) - [Notifying FXPs of completed payments | Nexus Payments Docs](#notifying-fxps-of-completed-payments-nexus-payments-docs) - [Managing Liquidity as an SAP | Nexus Payments Docs](#managing-liquidity-as-an-sap-nexus-payments-docs) - [Role and responsibilities of the Instant Payment System Operator (IPSO) | Nexus Payments Docs](#role-and-responsibilities-of-the-instant-payment-system-operator-ipso-nexus-payments-docs) - [SAP onboarding of FXPs (or foreign PSPs) | Nexus Payments Docs](#sap-onboarding-of-fxps-or-foreign-psps-nexus-payments-docs) - [MESSAGE: camt.054 Bank to Customer Debit Credit Notification | Nexus Payments Docs](#message-camt-054-bank-to-customer-debit-credit-notification-nexus-payments-docs) - [Obligations on the SAP | Nexus Payments Docs](#obligations-on-the-sap-nexus-payments-docs) - [Key Points | Nexus Payments Docs](#key-points-nexus-payments-docs) - [Validations, Duplicates & Fraud | Nexus Payments Docs](#validations-duplicates-fraud-nexus-payments-docs) - [Quotes | Nexus Payments Docs](#quotes-nexus-payments-docs) - [Payment Process for the Destination SAP | Nexus Payments Docs](#payment-process-for-the-destination-sap-nexus-payments-docs) - [Payment Process for the Source SAP | Nexus Payments Docs](#payment-process-for-the-source-sap-nexus-payments-docs) - [pacs.002 Differences from CPMI/CBPR+ Guidelines | Nexus Payments Docs](#pacs-002-differences-from-cpmi-cbpr-guidelines-nexus-payments-docs) - [Adherence to CPMI Harmonised ISO 20022 Data Requirements | Nexus Payments Docs](#adherence-to-cpmi-harmonised-iso-20022-data-requirements-nexus-payments-docs) - [MESSAGE: pacs.004 Payment Return (Not yet supported) | Nexus Payments Docs](#message-pacs-004-payment-return-not-yet-supported-nexus-payments-docs) - [Reconciliation reports | Nexus Payments Docs](#reconciliation-reports-nexus-payments-docs) - [Recall Requests | Nexus Payments Docs](#recall-requests-nexus-payments-docs) - [Joining Nexus as an SAP | Nexus Payments Docs](#joining-nexus-as-an-sap-nexus-payments-docs) - [General Usage of ISO 20022 | Nexus Payments Docs](#general-usage-of-iso-20022-nexus-payments-docs) - [Intermediary Agents (SAPs) | Nexus Payments Docs](#intermediary-agents-saps-nexus-payments-docs) - [Rejects | Nexus Payments Docs](#rejects-nexus-payments-docs) - [Unsuccessful Payments (Exceptions) | Nexus Payments Docs](#unsuccessful-payments-exceptions-nexus-payments-docs) - [Specific Message Elements | Nexus Payments Docs](#specific-message-elements-nexus-payments-docs) - [Fees | Nexus Payments Docs](#fees-nexus-payments-docs) - [Additional optional APIs | Nexus Payments Docs](#additional-optional-apis-nexus-payments-docs) - [MESSAGE acmt.023 Identification Verification Request | Nexus Payments Docs](#message-acmt-023-identification-verification-request-nexus-payments-docs) - [Disputes | Nexus Payments Docs](#disputes-nexus-payments-docs) - [Investigation & Enquiry | Nexus Payments Docs](#investigation-enquiry-nexus-payments-docs) - [pacs.008 Differences from CPMI Harmonisation Requirements | Nexus Payments Docs](#pacs-008-differences-from-cpmi-harmonisation-requirements-nexus-payments-docs) - [Translation To/From Domestic Message Formats | Nexus Payments Docs](#translation-to-from-domestic-message-formats-nexus-payments-docs) - [Purpose Codes | Nexus Payments Docs](#purpose-codes-nexus-payments-docs) - [Overview | Nexus Payments Docs](#overview-nexus-payments-docs) - [Compatibility with Instant Payments Plus (IP+) | Nexus Payments Docs](#compatibility-with-instant-payments-plus-ip-nexus-payments-docs) - [Currencies | Nexus Payments Docs](#currencies-nexus-payments-docs) - [Terms and Conditions of Use | Nexus Payments Docs](#terms-and-conditions-of-use-nexus-payments-docs) - [Returns | Nexus Payments Docs](#returns-nexus-payments-docs) - [Processing payments as an SAP | Nexus Payments Docs](#processing-payments-as-an-sap-nexus-payments-docs) - [Translating To/From ISO 20022 Codes | Nexus Payments Docs](#translating-to-from-iso-20022-codes-nexus-payments-docs) - [Financial Institutions | Nexus Payments Docs](#financial-institutions-nexus-payments-docs) - [ISO 20022 Messages | Nexus Payments Docs](#iso-20022-messages-nexus-payments-docs) - [MESSAGE: pacs.008 FI to FI Customer Credit Transfer | Nexus Payments Docs](#message-pacs-008-fi-to-fi-customer-credit-transfer-nexus-payments-docs) - [MESSAGE acmt.024 Identification Verification Report | Nexus Payments Docs](#message-acmt-024-identification-verification-report-nexus-payments-docs) - [Fees and Amounts | Nexus Payments Docs](#fees-and-amounts-nexus-payments-docs) - [Detailed Flow in Source Country (Sending) | Nexus Payments Docs](#detailed-flow-in-source-country-sending-nexus-payments-docs) - [Countries | Nexus Payments Docs](#countries-nexus-payments-docs) - [Detailed Flow in Destination Country (Receiving) | Nexus Payments Docs](#detailed-flow-in-destination-country-receiving-nexus-payments-docs) - [Cookies Notice | Nexus Payments Docs](#cookies-notice-nexus-payments-docs) - [How the Destination IPS initiates the payment via the Destination SAP | Nexus Payments Docs](#how-the-destination-ips-initiates-the-payment-via-the-destination-sap-nexus-payments-docs) - [Quotes | Nexus Payments Docs](#quotes-nexus-payments-docs) - [Address Types and Inputs | Nexus Payments Docs](#address-types-and-inputs-nexus-payments-docs) - [MESSAGE pacs.002 Payment Status Report | Nexus Payments Docs](#message-pacs-002-payment-status-report-nexus-payments-docs) --- # Nexus Overview | Nexus Payments Docs ![Page cover](https://docs.nexusglobalpayments.org/~gitbook/image?url=https%3A%2F%2F260996932-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdlTzGEXDmi664xppppmm%252Fuploads%252Fgit-blob-485fcaeee76598cc759551042799ae45e406a723%252FiStock-1447176645.jpg%3Falt%3Dmedia&width=1248&dpr=3&quality=100&sign=46955106&sv=2) [hashtag](https://docs.nexusglobalpayments.org/#enabling-instant-cross-border-payments) Enabling instant cross-border payments ----------------------------------------------------------------------------------------------------------------------------------- Nexus Global Payments (NGP) is a multilateral payment scheme dedicated to transforming cross-border transactions in line with the G20 Roadmap for Enhancing Cross-border Payments targets of speed, cost, accessibility, and transparency. This site contains detailed technical and functional information about Nexus, and is written for the payment system operators, banks, payment service providers and FX Providers who may be participating in Nexus. * If you are new to Nexus, we recommend starting with **chapter 2** of the [latest (2024) Nexus reportarrow-up-right](https://www.nexusglobalpayments.org/wp-content/uploads/2025/03/Project-Nexus-Report-Phase-3.pdf) for an overview of the scheme & governance, business model and technology architecture of Nexus. This site contains detailed **technical documentation,** covering: * [ISO 20022 message specifications](https://docs.nexusglobalpayments.org/messaging-and-translation/message-guidelines-excel) for Nexus * [API specifications](https://docs.nexusglobalpayments.org/apis/overview) circle-exclamation Nexus is not yet operational, and the information on this site will be updated as the design of Nexus is refined and improved. Over 100 countries already have instant (or "fast") payment systems that allow people to send money to each other within seconds. However, sending money abroad is often still slow and expensive. **Connecting these domestic payment systems internationally could improve the speed, cost and transparency of cross-border payments.** **Nexus is designed to standardise the way that these systems connect to each other.** Rather than a payment system operator building custom connections for every new country that it connects to, the operator can make one connection to the Nexus platform. This single connection allows an instant payments system to reach all other countries in the network. Nexus could significantly accelerate the growth of instant cross-border payments The Nexus blueprint has been developed over 3 years with significant input from instant payment system operators, central banks, commercial banks and payment service providers and FX providers who have a significant presence in FX markets and cross-border payments. We welcome further [feedback and suggestionsarrow-up-right](https://www.nexusglobalpayments.org/contact-us/) to enhance the blueprint. ### [hashtag](https://docs.nexusglobalpayments.org/#next-steps-for-nexus) Next steps for Nexus Originally conceptualised and developed by the Bank for International Settlements (BIS) in collaboration with central banking partners, Nexus standardises the way instant payment systems (IPS) connect across countries. To bring this vision to life, Nexus Global Payments (NGP) was established on March 26, 2025 by the central banks and IPS operators of India, Malaysia, the Philippines, Singapore, and Thailand. These pioneering jurisdictions form the inaugural cohort of Nexus owners provided the foundational capital to build and scale the platform. As we grow, we aim to welcome additional participants and owners, fostering a truly global and interoperable payment network.
 NGP is a not-for-profit organisation incorporated in Singapore, which is dedicated to managing the Nexus scheme and advancing the mission: to enable fast , efficient, and safe cross-border payments at scale. With NGP at the helm, Nexus has transitioned from a BIS-led initiative to an independent and collaborative effort, to shape the future of global payments. circle-info ### [hashtag](https://docs.nexusglobalpayments.org/#read-the-latest-july-2024-report) Read the latest (July 2024) Report This [**overview report**arrow-up-right](https://www.nexusglobalpayments.org/wp-content/uploads/2025/03/Project-Nexus-Report-Phase-3.pdf) explains the benefits of linking IPS to provide cross-border payments and how Nexus could accelerate the growth of instant cross-border payments. It describes the scheme & governance, business model and technology architecture for Nexus. It builds on a year-long collaboration with 5 central banks and their payment system operators. ![](https://docs.nexusglobalpayments.org/~gitbook/image?url=https%3A%2F%2F260996932-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdlTzGEXDmi664xppppmm%252Fuploads%252Fgit-blob-4a82fa0407d838d0a19e8c359f895e0be636a0d9%252FReport%2520Cover%2520for%2520Gitbook.png%3Falt%3Dmedia&width=300&dpr=3&quality=100&sign=3fd6ac7d&sv=2) (Use of this website and the Nexus materials is subject to the [terms and conditions](https://docs.nexusglobalpayments.org/legal/copyright-terms) .) [NextHow to use this sitechevron-right](https://docs.nexusglobalpayments.org/introduction/how-to-use-this-site) Last updated 1 month ago --- # How to use this site | Nexus Payments Docs We recommend starting by reading **chapter 2 of the** [**2024 overview report**arrow-up-right](https://www.nexusglobalpayments.org/wp-content/uploads/2025/03/Project-Nexus-Report-Phase-3.pdf) for a non-technical overview of how Nexus works. The rest of this site gives a more technical overview of Nexus, tailored at professionals in the payments industry. Each section begins with a **60-second summary.** * [Payment Setup](https://docs.nexusglobalpayments.org/payment-setup/key-points) describes the scope of Nexus payments and how they are setup from the Sender's perspective. It describes some of the information that is exchanged between the Sender's bank (the Source PSP) and Nexus. * [Addressing & Proxy Resolution](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/key-points) describes how payments in Nexus can be addressed using proxies (like a mobile number), International Bank Account Numbers or local account numbers. It also describes the features that allow the Sender to confirm the identity of the payee. * [FX Provision](https://docs.nexusglobalpayments.org/fx-provision/key-points) describes the role of financial institutions who swap the sender's currency for the recipient's. * [Payment Processing](https://docs.nexusglobalpayments.org/payment-processing/key-points) describes how banks or payment service providers (PSPs) and instant payment system operators (IPSO) should process Nexus payments, and what to do when something goes wrong. * [Settlement Access Provision](https://docs.nexusglobalpayments.org/settlement-access-provision/key-points) describes the role of the financial institutions who provide accounts to FX Providers (and some foreign PSPs) so that they can provide FX to Nexus payments, despite not being a full member of a country's IPS. * [Messaging & Translation](https://docs.nexusglobalpayments.org/messaging-and-translation/key-points) describes the specific ISO 20022 messages that are used in Nexus. It also describes how countries who do not use ISO 20022 domestically should translate to and from the Nexus standard messages. circle-info This site is a live document, and will be regularly updated with the latest specifications as the project advances. We welcome feedback and suggestions for improvement to the design of Nexus. [PreviousNexus Overviewchevron-left](https://docs.nexusglobalpayments.org/) [NextTerminologychevron-right](https://docs.nexusglobalpayments.org/introduction/terminology) Last updated 6 months ago --- # Scope of Nexus payments | Nexus Payments Docs Nexus supports account-to-account payments between individuals (known as person-to-person (P2P) and consumer-to-consumer (C2C)) and businesses (B2B), or between individuals and businesses (P2B, B2P). These payments are initiated by the sender entering a proxy, such as a mobile number, or account details into the app of the Sender's PSP. circle-exclamation This guide does not yet cover payments that are initiated by scanning a QR code, including: * proxy payments, where the proxy is embedded in a QR code * “merchant payments”, eg payments from a customer to a retailer or other business, using dynamic QR codes at the point of sale (either physical or e-commerce). These features will be added to Nexus in due course. Nexus currently supports **Single Instant Cross-Border Cross-Currency Payments:** _**“Single payment”**_ Nexus supports single payments only. A `pacs.008` payment instruction message sent to Nexus must only contain a single transaction. Nexus will process each payment individually and PSPs will accept/reject each Nexus payment individually. circle-info **Nexus does not accept bulk/batch payment instructions.** However, it is acceptable for a PSP to receive a bulk/batch payment file from its customers (or for an IPS to receive a bulk/batch payment file from its PSPs), “debulk” the file and submit the payments one-by-one as individual payments through Nexus. The Nexus Scheme Rulebook requirements will apply for these payments in full including requirements regarding transparency of fees, timelines and compliance checks. It will be the responsibility of the Source PSP (or IPS) to correlate the individual transactions (and their responses) back to the original batch/bulk file, if required. _**“Instant”**_ Nexus processes instant payments. A _domestic_ instant payment is defined as a payment executed end-to-end, where the funds being transferred from the account of a Sender are made available in the account of the Recipient, irrevocably, within seconds (typically within 20 seconds). Nexus combines two _domestic_ instant payments into a cross-border instant payment. **“Cross-Border, Cross-Currency”** Nexus is designed for instant payments requiring a currency conversion, using an FX Provider. See [FX Provision](https://docs.nexusglobalpayments.org/fx-provision/key-points) . triangle-exclamation Nexus does not currently support payments to and from the same currency (even if they are in different countries) [PreviousKey Pointschevron-left](https://docs.nexusglobalpayments.org/payment-setup/key-points) [NextSteps 1-2: Country, Currency & Amountchevron-right](https://docs.nexusglobalpayments.org/payment-setup/steps-1-2-country-currency-and-amount) Last updated 18 days ago --- # Steps 1-2: Country, Currency & Amount | Nexus Payments Docs circle-info The rest of this section assumes that readers are familiar with the main actors in Nexus: Payment Service Providers (PSPs), Instant Payment System Operators (IPSOs), Foreign Exchange Providers (FXPs) and Settlement Access Providers (SAPs). For a primer on each of these actors please see [Chapter 2.3 of the Nexus (2024) reportarrow-up-right](https://www.nexusglobalpayments.org/wp-content/uploads/2025/03/Project-Nexus-Report-Phase-3.pdf) . The example user journey below demonstrates how an individual Sender would use their existing PSP channel (eg an app) to make a payment through Nexus, and describes the steps taken by Nexus behind the scenes. circle-exclamation Note that there is no "Nexus app" and payment Senders do not register with or interact directly with Nexus. The app shown is a mockup designed to give an example of how a PSP may integrate the service into their own app. ### [hashtag](https://docs.nexusglobalpayments.org/payment-setup/steps-1-2-country-currency-and-amount#toc116457912) Step 1: Ask the Sender to select the country and currency 1. Using data retrieved from the `GET /countries/` API operation, the Source PSP (Sender's PSP) can display a dropdown Countries list to the Sender via the Source PSP’s app or other channel. (Left and middle figure below.) 2. The response to `GET /countries/` lists all Nexus-enabled countries and the currencies available in that country. If the Sender selects a country with more than one currency, the PSP should immediately: 1. Display a second form element (eg `**` 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. circle-info 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. [PreviousFinancial Institution Identificationchevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification) [NextExampleschevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples) Last updated 18 days ago --- # Financial Institution Identification | Nexus Payments Docs [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification#using-with-account-id) 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. circle-info When the address type is ACCT, the response from the `Address Inputs` API will automatically include a field for the Financial Institution Identification. ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification#using-with-a-proxy) Using with a Proxy circle-info In some countries, such as the Philippines, the same proxy can be registered to multiple financial institutions. Therefore it is necessary to collect the Financial Institution Identification for the Recipient. In these (rare) cases, the response from the Address Types API will automatically include a field for the Financial Institution Identification. ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification#table-financial-institution-identification-types) TABLE: Financial Institution Identification Types The following Financial Institution Identification types are defined in ISO 20022. **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_ [PreviousAddress Inputschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-inputs) [NextList of PSPschevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/list-of-psps) Last updated 17 days ago * [Using with Account Id](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification#using-with-account-id) * [Using with a Proxy](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification#using-with-a-proxy) * [TABLE: Financial Institution Identification Types](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification#table-financial-institution-identification-types) --- # Obligations of PSPs using the Proxy Directory | Nexus Payments Docs The obligations of PSPs when using the proxy directory are defined in the Nexus Rulebook. In particular: * **Appropriate use of the service:** The Source PSP is obliged to only send proxy resolution requests for the purpose of initiating a payment. However, the Source PSP is not obliged to complete a payment after initiating a proxy resolution (for example if the Sender decides not to proceed with the payment). * **Restricted use of the data:** When data is returned in response to a proxy resolution request, the PSP must use that data only for the purpose of processing this transaction, and not for any other purpose. * **Confirmation of payee:** Where the Recipient’s name is provided to the Source PSP (by the Proxy Directory or Destination PSP), the Source PSP must display this name to the Sender before they confirm the payment. This provides the Sender with greater confidence that they are sending funds to the correct account and reduces the chance of the proxy being used for fraud. * **Prevention of abuse:** * The Source PSP should monitor the number of proxy resolution requests a specific Sender makes to ensure that they are not ‘phishing’ for account details. At a basic level, this may involve imposing a timeout for the user if they look up, for example, five different proxies in a short period without initiating a payment (ie a rate limit on proxy resolution requests). * When sending acmt.023 proxy or account resolution requests, the Source PSP **should** include an unique Identification for the Sender which will allow the Proxy Directory Operator to identify whether multiple requests are initiated by the same individual in short succession. See [Messaging & Translation](https://docs.nexusglobalpayments.org/messaging-and-translation/key-points) for the correct placement of this Identification. [PreviousObligations on the Proxy Directory Operatorchevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/obligations-on-the-proxy-directory-operator) [NextOnboarding a Proxy Directory Operator onto Nexuschevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/onboarding-a-proxy-directory-operator-onto-nexus) Last updated 6 months ago --- # Address Inputs | Nexus Payments Docs 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) circle-exclamation 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 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). #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-inputs#toc163730911) 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. _MNBO, ACCT, IBAN_ This code can be mapped to the app user’s language. Title Map, 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”). ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-inputs#toc163730912) [PreviousAddress Typeschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-types) [NextFinancial Institution Identificationchevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/financial-institution-identification) Last updated 17 days ago --- # Obligations on the Proxy Directory Operator | Nexus Payments Docs ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/obligations-on-the-proxy-directory-operator#toc163730935) Obligations of the Proxy Directory Operator When the PDO is enabled through Nexus, the PDO needs to fulfil the following obligations: **Availability** * The PDO should have the ability to process proxy resolution requests, with the required availability (in principle 24/7/365), and with business continuity arrangements. * The PDO should maintain availability of at least 99.5%. **Accuracy** * The PDO verifies, before a proxy can be shared through Nexus, that the proxy is in control of the account holder (i.e. payee), or otherwise authorized by the possessor of the proxy to link it to the Recipient’s account. The PDO guarantees that the proxy database will be kept current and changes made by proxy holders will be processed immediately. * The PDO is obligated to verify that the account holder name provided by the service is accurate (for example, by only allowing changes to the name associated to the proxy to be made by the PSP providing that account, rather than by the person controlling the proxy itself). **Data privacy and consent** * The PDO needs to ensure that all required consents have been collected for any information disclosed to and via Nexus. The method to do this should be compliant with local standards where the information is collected. * The PDO will ensure that (contractual and implicit) privacy expectations of end users (both on the sending and receiving end of transactions) are met. **Compliance** * The PDO will keep track of queries processed for the purpose of providing an audit trail to relevant parties involved. * The PDO establishes a secure channel with the Nexus Gateway for the protection of sensitive data. [PreviousRole of the Proxy Directory Operator (PDO)chevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo) [NextObligations of PSPs using the Proxy Directorychevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/obligations-of-psps-using-the-proxy-directory) Last updated 6 months ago --- # Role of the Proxy Directory Operator (PDO) | Nexus Payments Docs In most IPS, a proxy (or "alias") cannot be used directly in a payment instruction (such as ISO 20022 [`pacs.008`arrow-up-right](https://github.com/bis-ih-fusse/nexus-temp/blob/main/messaging-and-translation/message-pacs.008-fi-to-fi-customer-credit-transfer) ). Instead, the proxy must first be sent to the local **proxy directory**, via a proxy resolution request. The proxy directory service will then lookup and return the corresponding account details. **Proxy Directory Operators (PDOs)** provide and maintain the databases which contain a list of proxies and the accounts and FIs that each proxy is associated with. PDOs typically provide: * A **database of proxies** and associated Financial Institution Identifications and Account Identifications * A method for account holders to **register and deregister proxies**, or change the account linked to a specific proxy, via their authorized PSPs * A method for PSPs to make a **proxy resolution request** to the proxy directory (ie sending a proxy and receiving back a Financial Institution Identification, Account Identification and name of the account holder) circle-info In many countries (but not all), the PDO is the same entity as the Instant Payment System Operator (IPSO), and therefore the instant payment _scheme_ and proxy resolution _scheme_ are managed by the same entity, and the PDO and IPSO are the same entity. [PreviousMasking of Display Nameschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/masking-of-display-names) [NextObligations on the Proxy Directory Operatorchevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/obligations-on-the-proxy-directory-operator) Last updated 6 months ago --- # Masking of Display Names | Nexus Payments Docs * As per normal practice, the Recipient’s full name **must** be shared in full (unmasked) with the Source PSP to support sanctions screening. * This information should be provided by the Proxy Directory or Destination PSP in the `_IdVrfctnReq/Rpt/UpdtdPtyAndAcctId/Pty/Nm_` element of the `acmt.024` message. See [MESSAGE acmt.024 Identification Verification Report](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.024-identification-verification-report) * The Proxy Directory or 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 Proxy Directory or Destination PSP is responsible for masking the name** according to their own privacy and data protection preferences, policies or local regulations. triangle-exclamation Nexus will not mask or alter the information provided in the `_IdVrfctnReq/Rpt/UpdtdPtyAndAcctId/Acct/Nm_` element of the `acmt.024` message. [PreviousStep 4: Source PSP processes the resultschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-4-source-psp-processes-the-results) [NextRole of the Proxy Directory Operator (PDO)chevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo) Last updated 6 months ago --- # Step 4: Source PSP processes the results | Nexus Payments Docs The Source PSP will now receive an `acmt.024` response message from Nexus. 1. The Source PSP will check the `acmt.024` to see if the proxy or account resolution has been successful. * If the proxy or account resolution has **failed**, the Source PSP will display the reason to the Sender, based on the _Reason Code_ provided. (For example: “_This proxy is not associated with any account.”_) 2. If the proxy resolution is **successful**, the Source PSP must: 1. Check if the display name is provided in the `acmt.024` response message (in the `Account > Name` element): 1. **If a display name is provide**, the Source PSP should the display name to the Sender and ask them to confirm that this is the name they’re expecting to see (see [Step 9 of the User Journey](https://docs.nexusglobalpayments.org/payment-setup/steps-7-9-addressing-proxy-resolution-and-confirmation-of-payee#toc116457922) ). 2. **If no display name is provided**, the app should show the Sender a warning to the effect of “We were unable to check the name of the account holder. Please double-check the account details are correct before sending the payment.” The Sender may proceed with the payment at their own discretion. triangle-exclamation If no real name was provided in `_Party > Name_`_,_ the Source PSP does not have sufficient information about the Recipient to complete the necessary compliance and sanctions screening checks. In this case, the Source PSP **must** ask the Sender to provide this information. (This is the least preferred outcome as it relies on potentially inaccurate information from the Sender, rather than verified information from the Destination PSP or Proxy Directory.) [PreviousStep 3: Account Resolution Messaging Sequencechevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence) [NextMasking of Display Nameschevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/masking-of-display-names) Last updated 6 months ago --- # Address Types | Nexus Payments Docs 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 Setarrow-up-right](https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets) The table below lists the possible address type codes in Nexus. The most commonly accepted address types are bolded. circle-info Even IPS that use ISO 20022 domestically often use proprietary codes to describe proxies, for example, using "MSISDN" rather than the ISO 20022 "MBNO". There are particular translation challenges to consider around the use of proxy code - please see [Translating To/From ISO 20022 Codes](https://docs.nexusglobalpayments.org/messaging-and-translation/translating-to-from-iso-20022-codes) for further detail. ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-types#toc163730908) Table: Address types & codes **CODE (ISO 20022)** **MEANING** **TYPE** **NOTES** **IBAN** **International Bank Account Number** Account Identification Typically defines country, PSP and account. (In some countries, the BIC or Clearing System Member Id is not included in the IBAN, so separate enrichment tables must be used to map a subset of the IBAN to the relevant FI Id.) **ACCT** **Account Identification (to be used in conjunction with a Financial Institution Identification)** Account Identification **Must** be used in conjunction with a Financial Institution Identification (see table below) **BIID** Biller Subscriber Identification Proxy Id **CINC** **Certificate of Incorporation Number** Proxy Id Company registration number COTX Corporate Tax Identification Proxy Id COID Country Authority Identification Proxy Id CUST Customer identification Number Proxy Id DNAM Domain Name (Internet) Proxy Id DRLC Driver License Number Proxy Id EIDN Electronic Identification Proxy Id **EMAL** **Email address** Proxy Id EWAL E-Wallet identification Proxy Id PVTX Individual tax identification Proxy Id LEIC Legal Entity Identifier Code Proxy Id **MBNO** **Mobile phone number** Proxy Id Most commonly accepted proxy type **NIDN** **National identification number** Proxy Id CCPT Passport number Proxy Id SHID Scheme identification Number Proxy Id Often used for virtual payment addresses SOSE Social Security Number Proxy Id TELE Telephone Number (land line) Proxy Id UBIL Utilities Subscription Identification Proxy Id VIPN Vehicle Identification Plate Number Proxy Id TOKN Virtual payment addresses (treated as a “token”) Proxy Id [PreviousAddress Types & Inputschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs) [NextAddress Inputschevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-inputs) Last updated 17 days ago --- # Proxy & Account Resolution Process | Nexus Payments Docs circle-info #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process#toc163730920) Note: Support for ISO 20022 acmt.023 and acmt.024 Nexus uses the ISO 20022 messages [`**acmt.023**`](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.023-identification-verification-request) and [`**acmt.024**`](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.024-identification-verification-report) for all communication related to proxy resolution or account resolution. **The remainder of this guide assumes that the IPS operator, proxy directory and member PSPs can support the** `**acmt.023 & acmt.024**` **messages according to the Nexus usage guidelines.** However, this is not the case in many countries. IPSOs that do not currently support `acmt.023` and`acmt.024` must either: * translate these messages to the relevant domestic format, or * adapt their systems (including the proxy directory, and the systems of their member PSPs) to support these messages. These options and the translation process are described in [Messaging & Translation](https://docs.nexusglobalpayments.org/messaging-and-translation/key-points) . ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process#toc163730921) Simple Overview The diagram below shows the proxy and account resolution process at a high level. circle-info (The user experience in the app is shown in more detail (with visual examples) in [Payment Setup](https://docs.nexusglobalpayments.org/payment-setup/key-points) ). #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process#figure-proxy-and-account-resolution-flow-diagram-simple-overview) Figure: Proxy & Account Resolution Flow Diagram (Simple Overview) ![](https://docs.nexusglobalpayments.org/~gitbook/image?url=https%3A%2F%2F260996932-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdlTzGEXDmi664xppppmm%252Fuploads%252Fgit-blob-a65081c105ef6c057b3d8219c6c9ebeb530ad54f%252F0%2520%2811%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=208c48f4&sv=2) High level flow diagram showing the proxy and account resolution process in Nexus 1. A Sender can enter either the Recipient’s proxy ID or account ID into their PSP’s app 2. The Source PSP will send this information to Nexus 3. If the Sender provided a proxy, Nexus will connect to the relevant proxy directory and request the corresponding account details 1. The proxy directory will return the corresponding account details. 4. If either (a) the Sender provided an account ID, or (b) the proxy resolution response from the Proxy Directory includes the account ID, Nexus will: 1. Check if the Destination PSP is able to accept account resolution requests. 1. If so, Nexus will send an account resolution request to the Destination PSP 5. Nexus will combine the information from the proxy directory and the Destination PSP (if an account resolution request was sent), and send this back to the Source PSP 6. The Source PSP will check the information in the response: 1. If a Display Name was provided, the Source PSP will ask the Sender to confirm that the payee is who they expect 2. If no Display Name is provided, the Sender will be advised to proceed with the payment at their own risk 3. If no other information is provided (such as the full name on the account), then the Source PSP will need to ask the Sender to provide this information so that the Source PSP can perform compliance and sanctions screening checks on the Recipient. The rest of this section covers those steps in more detail. [PreviousExampleschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples) [NextStep 1: Sender inputs proxy or account detailschevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-1-sender-inputs-proxy-or-account-details) Last updated 17 days ago --- # Onboarding a Proxy Directory Operator onto Nexus | Nexus Payments Docs [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/onboarding-a-proxy-directory-operator-onto-nexus#toc163730933) The PDO must provide Nexus with reference data on the available address types and input fields ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Nexus needs to be aware of the different [address types](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-types) (such as IBAN, account, mobile) and [address inputs](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-inputs) available in each country, so that it can provide this information to Source PSPs through the Nexus APIs. Therefore, when a new IPSO (or proxy service) is onboarded with Nexus, the IPSO must provide Nexus with reference data describing each address type and the input fields (address inputs) for that address type. This information can be provided via the Nexus Service Desk or APIs. The IPS Operator is responsible for ensuring that the data is kept up to date. [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/onboarding-a-proxy-directory-operator-onto-nexus#toc163730934) PDO must onboard with the local IPS Operator ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Nexus Scheme expects the IPS Operator to take on the responsibility for connecting its instance of the Nexus Gateway to the domestic proxy directory, particularly where: * The IPS Operator and the PDO are the same entity, AND/OR * In each country that the IPS Operator provides payment services to, there is only one PDO circle-exclamation Cases where there are multiple IPSOs or multiple Proxy Directories in a particular country or jurisdiction may need to be handled differently. The approach to this scenario will be developed in a future phase of Nexus development. [PreviousObligations of PSPs using the Proxy Directorychevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/obligations-of-psps-using-the-proxy-directory) [NextKey Pointschevron-right](https://docs.nexusglobalpayments.org/fx-provision/key-points) Last updated 6 months ago * [The PDO must provide Nexus with reference data on the available address types and input fields](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/onboarding-a-proxy-directory-operator-onto-nexus#toc163730933) * [PDO must onboard with the local IPS Operator](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/role-of-the-proxy-directory-operator-pdo/onboarding-a-proxy-directory-operator-onto-nexus#toc163730934) --- # Step 2: Proxy Resolution Messaging Sequence | Nexus Payments Docs Following on from [Step 1](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-1-sender-inputs-proxy-or-account-details) , assuming the Sender entered a proxy, the Source PSP will send Nexus an ISO 20022 [`acmt.023`](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.023-identification-verification-request) message that includes the proxy details. ![](https://docs.nexusglobalpayments.org/~gitbook/image?url=https%3A%2F%2F260996932-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdlTzGEXDmi664xppppmm%252Fuploads%252Fgit-blob-a438c5f30e058e0dd92a6e1e4514e363c76d95ec%252Fimage%2520%2818%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=ae7a6296&sv=2) Proxy resolution flow diagram ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence#id-1.-nexus-message-transformation) **1\. Nexus (Message Transformation)** Nexus will: * look for the Country Code in the `_Assignee > Agent > PostalAddress > Country_` element * identify the relevant proxy directory in that country, and * update the Assignee to the BIC of the proxy directory (or its parent IPS Operator). This is the only change that is made to the message. ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence#id-2.-nexus-greater-than-destination-proxy-directory) **2\. Nexus -> Destination Proxy Directory** Nexus will send the proxy resolution request to the Destination Proxy Directory Operator. The message will be formatted as an ISO 20022 `acmt.023` message. The PDO must be able to accept the message in this format. If the _domestic_ proxy resolution message format is different, the **IPSO is responsible for translating the message** from the Nexus `acmt.023` to the domestic format message before processing the proxy resolution request (See [Messaging & Translation](https://docs.nexusglobalpayments.org/messaging-and-translation/key-points) for further details.) #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence#scenario-1-no-associated-proxy) **Scenario 1: No associated proxy** The Destination Proxy Directory should first check if the proxy is associated with an account. If there is no associated account, the proxy directory should respond with an `acmt.024` response including the appropriate error code in the `_Report > Verification > Reason > Code_` element. (See [Error codes](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.024-identification-verification-report#toc143525641) for further information.) #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence#scenario-2-proxy-successfully-resolved) **Scenario 2: Proxy successfully resolved** If the proxy successfully maps to an account, the proxy directory should prepare and return an `acmt.024` response message that contains, **at a minimum:** * Account details, in the form of either: * an **IBAN**, OR * the **Financial Institution Identification** (eg BIC) AND the **Account Identification** of the linked account * the **real name** associated with the account (wherever possible) – this will be used by the Source PSP when sanctions screening the Recipient. * This should be stored in the element `_UpdatedPartyAndAccountIdentification > Party > Name_`_._ * Note that wherever possible, the full real name should be returned, as this information supports accurate and automated sanctions screening. * a **display name** that can be shown to the Sender to allow them to confirm that the account holder is the intended Recipient. This could be the full name (where privacy and data protection rules allow this to be shown to the Sender) or a partially obscured name, depending on the proxy service. * This value should be in the element `_UpdatedPartyAndAccountIdentification > Account > Name_` circle-exclamation Note: this is a non-standard use of the _Account > Name_ element_,_ which should normally describe the name of the _account_ rather than the name of the account holder. Unfortunately, the `acmt.024` message structure does not currently have a dedicated element for a display name that can be shown to the Sender but which may be different from the real account holder name. The proxy directory should send this response back to the Nexus. See [**Step 3**](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence) below for details on how Nexus will handle this response. [PreviousStep 1: Sender inputs proxy or account detailschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-1-sender-inputs-proxy-or-account-details) [NextStep 3: Account Resolution Messaging Sequencechevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence) Last updated 6 months ago * [1\. Nexus (Message Transformation)](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence#id-1.-nexus-message-transformation) * [2\. Nexus -> Destination Proxy Directory](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence#id-2.-nexus-greater-than-destination-proxy-directory) --- # Step 1: Sender inputs proxy or account details | Nexus Payments Docs circle-info Note: The process below is shown with demonstration screens in [_Sending Payments > Steps 7-9 Addressing, Proxy and Confirmation of Payee_](https://docs.nexusglobalpayments.org/payment-setup/steps-7-9-addressing-proxy-resolution-and-confirmation-of-payee) . ![](https://docs.nexusglobalpayments.org/~gitbook/image?url=https%3A%2F%2F260996932-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdlTzGEXDmi664xppppmm%252Fuploads%252Fgit-blob-d10fcd0f61b9103c40e7e25fbb146b7da84282cb%252Fimage%2520%2817%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=f58e82ae&sv=2) Flow diagram for setup of the addressing form in the Source PSP's app 1. When the Sender selects the Destination Country for a payment in their PSP’s app, the Source PSP will call the `GET /countries/{countrycode}/addressTypes` API operation, specifying the country code. Nexus will respond with a full list of address types for that country, including any proxy types, Account Identification formats and/or IBAN. (See [_Address Types_](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/address-types) for details.) 2. The Source PSP will show the Sender a form allowing them to select one of the possible address types, according to the details they were given by the Recipient. 3. The Sender selects an address type (eg the “Mobile” option on the form; in the case of a payment to Singapore, this would select the address type with the ID “_SGMBNO”_). 4. The Source PSP will call the `GET /addressTypes/{addressTypeId}/inputs` API operation to retrieve the input fields that are required for this address type. circle-info The Source PSP could retrieve the address inputs for all address types in a single API call by using `GET /countries/{countryCode}/addressTypesAndInputs/` instead of `GET /countries/{countryCode}/addressTypes/` 1. The Source PSP’s app will use the address inputs to generate the app form to enter the address details 2. The Sender will enter the details that they were given by the Recipient (eg “+6580001234”). 3. The Source PSP’s app must validate that the address details entered by the Sender are in the correct format. These validation rules will be provided as regular expressions (regex) in the address inputs information provided by Nexus. This allows the PSP to validate the format of the data in-app, prior to any communication with Nexus or the proxy scheme. 4. If the Sender entered **proxy details**, the Source PSP will prepare an ISO 20022 [`acmt.023`](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.023-identification-verification-request) message, following the **usage guidelines for** **proxy resolution.** The Source PSP will send the `acmt.023` (or equivalent API request) to Nexus. 1. **See** [**Step 2**](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence) for further steps on proxy resolution. 5. If the Sender entered account details, the Source PSP will prepare an **ISO 20022** [**acmt.023**](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.023-identification-verification-request) message, following the **usage guidelines for** **account resolution.** The Source PSP will send the `acmt.023` (or equivalent API request) to Nexus. 1. **See** [**Step 3**](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence) for further steps on account resolution. [PreviousProxy & Account Resolution Processchevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process) [NextStep 2: Proxy Resolution Messaging Sequencechevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence) Last updated 17 days ago --- # Step 3: Account Resolution Messaging Sequence | Nexus Payments Docs At this step, Nexus has access to account details for the Recipient, from one of two sources: * An `acmt.023` message from the Source PSP, which includes the Account Identification and Financial Institution Identification provided by the Sender, OR * An `acmt.024` response from the Destination Proxy Directory, which includes the account details associated with the proxy provided by the Sender. If the Destination PSP is enabled to process `acmt.023` requests, Nexus will send an updated `acmt.023` to the Destination PSP to get verified information about the Recipient directly from the Destination PSP, as follows. circle-info Supporting account resolution is optional for each PSP, and Nexus would be aware of which PSPs are willing and able to support account resolution requests. Nexus would not send account resolution requests to PSPs that are unable to process them. ![](https://docs.nexusglobalpayments.org/~gitbook/image?url=https%3A%2F%2F260996932-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdlTzGEXDmi664xppppmm%252Fuploads%252Fgit-blob-cfe36dbfd5b7a4472bace03c9dfd4a2e498dc74e%252Fimage%2520%2819%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=623678be&sv=2) Account resolution flow diagram (click to expand) ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence#id-1.-nexus) **1\. Nexus** Nexus will: * look for the Agent Id in the `_Agent > FinancialInstitutionId_` element * check whether that Agent is reachable through Nexus * If not, Nexus will prepare an `actm.024` with the `_Report > Verification_` element set to “false” (since it is not possible to proceed with the payment) and the appropriate _Reason_ code (`_AGNT_`_,_ Incorrect Agent – see [Error codes](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.024-identification-verification-report#toc143525641) ). * check whether the Agent is able to process account resolution requests. (Not all PSPs will be able to; this information will be recorded by Nexus when a new PSP is onboarded.) * If the Destination PSP **can** accept account resolution requests, Nexus will: * update the Assignee for the message to the Destination PSP * forward the `acmt.023` request message to the Destination PSP (via the IPS that is connected to that Agent). * If the Destination PSP **cannot** accept account resolution requests: * If the Sender originally provided a proxy, Nexus will forward the `acmt.024` that was received from the Destination Proxy Directory in [Step 2](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence) * If the Sender originally provided account details, Nexus will prepare an `acmt.024` with the _Report > Verification_ element set to “false” (since account resolution was not possible) and the appropriate _Reason_ code (proposed to be `_AB08_` _– Offline Creditor Agent_). ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence#id-2.-destination-psp) **2\. Destination PSP** The Destination PSP should use the account ID provided to look up the corresponding account. * If the **account does not exist or is inactive**, they should return an `acmt.024` with the `_Report > Verification_` element set to “false” and the appropriate `_Reason_` code (such as `AC01`, `AC04`, `AC06` – see [Error codes](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.024-identification-verification-report#toc143525641) ). * If the **account is active**, they should prepare an acmt.024 response and add (to the `_UpdatedPartyAndAccountIdentification_` block) the following information: * the **real name** associated with the account (wherever possible) – this will be used by the Source PSP when sanctions screening the Recipient. * This should be in the element `_UpdatedPartyAndAccountIdentification > Party > Name_` * a **display name** that can be shown to the Sender to allow them to confirm the account holder is the intended Recipient. * This could be the full name (where privacy and data protection rules allow this to be shown to the Sender) or a partially obscured name, depending on the proxy service. * The Destination PSP is responsible for masking the name. * This value should be in the element `_UpdatedPartyAndAccountIdentification > Account > Name_` circle-exclamation Note: this is a non-standard use of _Account > Name_, which should normally describe the name of the _account_ rather than the account _holder_. Unfortunately, the `acmt.024` does not currently have a dedicated element for a display name that can be shown to the Sender but which may be different from the real account holder name. circle-info In addition, if the Destination PSP can supply some or all of the following information will support more efficient sanctions screening, with fewer false positive alerts: * Address * Date and Place of Birth * The Destination PSP should now prepare an `acmt.024` response and send it to Nexus. The flow diagram below explains how the Destination PSP should prepare the message. ![](https://docs.nexusglobalpayments.org/~gitbook/image?url=https%3A%2F%2F260996932-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FdlTzGEXDmi664xppppmm%252Fuploads%252Fgit-blob-d990b576598ade0e8c6684b5c2fae45c2c6e1561%252Fimage%2520%2820%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=bc0e567a&sv=2) Flow diagram: preparation of acmt.024 response by the Destination PSP ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence#id-3.-nexus-greater-than-source-ips-greater-than-source-psp) **3\. Nexus -> Source IPS -> Source PSP** Nexus will forward the `acmt.024` response (from the Destination PSP) to the Source PSP, via the IPS. See [**Step 4**](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-4-source-psp-processes-the-results) . triangle-exclamation In some jurisdictions, PSPs will be unwilling to share any information about the Recipient/Creditor before a payment is initiated. In this case, an alternative form of verification (often used in Europe) is to ask the Sender to provide information about the Recipient, and then ask the Destination PSP to confirm whether or not that information is accurate. This "**comparison"** or **"matching"** process will be developed for Nexus in a future phase of development. [PreviousStep 2: Proxy Resolution Messaging Sequencechevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-2-proxy-resolution-messaging-sequence) [NextStep 4: Source PSP processes the resultschevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-4-source-psp-processes-the-results) Last updated 6 months ago * [1\. Nexus](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence#id-1.-nexus) * [2\. Destination PSP](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence#id-2.-destination-psp) * [3\. Nexus -> Source IPS -> Source PSP](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process/step-3-account-resolution-messaging-sequence#id-3.-nexus-greater-than-source-ips-greater-than-source-psp) --- # Obligations & Compliance | Nexus Payments Docs circle-exclamation This page relates **only** to third-party FX Providers. For Source PSPs that provide their own FX, a different process applies. See [Payment setup for PSPs who provide their own FX](https://docs.nexusglobalpayments.org/payment-processing/payment-setup-for-psps-who-provide-their-own-fx) for details. The Nexus Scheme Rulebook provides detailed obligations for FX Providers. At a high level, these obligations include: [hashtag](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809576) Compliance -------------------------------------------------------------------------------------------------------------------- FX Providers must comply with all applicable regulations in the jurisdiction they are based in, as well as any applicable regulations in the jurisdiction to which they are providing FX. [hashtag](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809577) Sanctions screening ----------------------------------------------------------------------------------------------------------------------------- Unless otherwise required by a specific country’s regulatory regime, a third-party FXP is **not** obliged to perform sanctions screening on individual Nexus payments. The FXP’s counterparty is the Source PSP to whom they sell the Destination Currency, and the FXP does not deal with (or have information on) the Sender or Recipient. However, when an FXP is a member of an IPS and therefore acts as SAP to themselves, the entity _is_ responsible for screening the payment against applicable sanctions lists in their role as SAP, subject to local regulations. (See [Settlement Access Provision](https://docs.nexusglobalpayments.org/settlement-access-provision/key-points) .) [hashtag](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809578) Minimum commitment ---------------------------------------------------------------------------------------------------------------------------- FXPs must commit to providing FX to Nexus for a certain minimum duration (to be specified in the Nexus Scheme Rulebook) and must give a period of notice if they wish to stop providing FX. FXPs may choose to permanently withdraw from providing FX to Nexus. The Nexus Scheme Rulebook defines the process and minimum notice period for withdrawing from the scheme. [hashtag](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809579) Market maker role --------------------------------------------------------------------------------------------------------------------------- In general, FX Providers are expected to play a similar role to that of a market maker; this means that they are expected to always provide a quote for the payment corridors that they provide. If they do not wish to be committed for new payments, they may set a quote that is below the rest of the market, but they should not “exit the market” by providing no quote at all. This expectation is necessary to ensure that there is always liquidity available for Nexus payments and to avoid a situation where all FX Providers for a currency channel choose to “sit out” of the market (making payments through that channel impossible). The obligation to always quote also helps to ensure that FX rates will be dynamic and are likely to be broadly in line with other FX markets. An exception may need to be made for FXPs who do not have the technical capacity to quote 24/7. For example, some FXPs who do not have a global presence may only be able to quote in their country’s business hours. In this case, they would be expected to always provide active rates during their business hours but would be able to “exit” the market by withdrawing all their rates at the end of the business day. Over time and as they gain experience with Nexus payment flows, such FXPs should be able to develop the ability to automate rate provision and liquidity management outside of business hours, in order to start quoting 24/5 (Mon-Fri) and ultimately 24/7 (including weekends).​ [PreviousOnboarding PSPschevron-left](https://docs.nexusglobalpayments.org/fx-provision/onboarding-psps) [NextRevenue model for FXPschevron-right](https://docs.nexusglobalpayments.org/fx-provision/revenue-model-for-fxps) Last updated 11 days ago * [Compliance](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809576) * [Sanctions screening](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809577) * [Minimum commitment](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809578) * [Market maker role](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance#toc163809579) --- # Revenue model for FXPs | Nexus Payments Docs circle-exclamation This page relates **only** to third-party FX Providers. For Source PSPs that provide their own FX, a different process applies. See [Payment setup for PSPs who provide their own FX](https://docs.nexusglobalpayments.org/payment-processing/payment-setup-for-psps-who-provide-their-own-fx) for details. ### [hashtag](https://docs.nexusglobalpayments.org/fx-provision/revenue-model-for-fxps#toc163809581) Revenue model for FXPs As described in the Nexus Scheme Rulebook, FXPs are not permitted to: * make a deduction from the value of a Nexus payment as it flows through the FXP's accounts, or * charge a separate fee (“Invoiced Fee”) to PSPs for the FX service they provide. Therefore FXPs must set the exchange rates they offer via Nexus at a level that provides for all their own costs plus their expected profit margin. ### [hashtag](https://docs.nexusglobalpayments.org/fx-provision/revenue-model-for-fxps#toc163809582) Costs incurred by FXPs Key costs incurred by FX Providers will include: * The initial technical cost incurred by the FXP to integrate with Nexus * The costs of acquiring a particular currency (either purchased via wholesale FX markets, or borrowed, for example if the SAP provides the FXP with a line of credit) * The costs charged by Settlement Access Providers for account provision (if the FPX is not a member of the IPS in question) * All other costs of operation, onboarding PSPs, regulatory compliance etc. ### [hashtag](https://docs.nexusglobalpayments.org/fx-provision/revenue-model-for-fxps#toc163809583) Ensuring a competitive FX market Nexus is designed to ensure a competitive FX market: * **FX Providers are in competition with each other** to provide the best exchange rates for a given currency pair. * **PSPs have free choice over which FXP they use** (subject to the requirement that the PSP has completed the initial KYC and onboarding process with that FXP - see [Onboarding PSPs](https://docs.nexusglobalpayments.org/fx-provision/onboarding-psps) ) * When an FXP posts a quote to Nexus, they are informed of the **current leading market rate** for that corridor (but not the FXP offering that rate), so they can assess whether the rates they offer are competitive against the market as a whole. To have competitive pricing, there needs to be **more than one FX Provider for a specific corridor.** Without this, the sole FX Provider will have a monopoly on that corridor. Rates in a monopoly corridor will be less competitive, although users could switch to using other payment methods, so there is still some pressure on the FXP to offer rates broadly in line with the wider FX market. circle-exclamation The API credentials given to third-party FXPs will not allow them to use the `GET /quotes/` API and so they are unable to see the full breakdown of rates offered by their competitor FXPs. FXPs who are also PSPs will have two separate sets of API credentials and must not share the information from the `GET /quotes/` response between the payments and FX/Treasury departments. [PreviousObligations & Compliancechevron-left](https://docs.nexusglobalpayments.org/fx-provision/obligations-and-compliance) [NextRates from Third-Party FX Providerschevron-right](https://docs.nexusglobalpayments.org/fx-provision/rates-from-third-party-fx-providers) Last updated 6 months ago * [Revenue model for FXPs](https://docs.nexusglobalpayments.org/fx-provision/revenue-model-for-fxps#toc163809581) * [Costs incurred by FXPs](https://docs.nexusglobalpayments.org/fx-provision/revenue-model-for-fxps#toc163809582) * [Ensuring a competitive FX market](https://docs.nexusglobalpayments.org/fx-provision/revenue-model-for-fxps#toc163809583) --- # Examples | Nexus Payments Docs [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#address-types) 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. circle-exclamation The ISO 20022 external code set does not have a code type for proxy directory or proxy scheme. It may be necessary to register a new code type for this purpose. Copy { "addressTypes": [\ {\ "addressTypeId": "IDACCT",\ "countries": [\ "ID"\ ],\ "code": "ACCT",\ "clearingSystemId": "BIFST",\ "displayOrder": 3\ },\ {\ "addressTypeId": "IDEMAL",\ "countries": [\ "ID"\ ],\ "code": "EMAL",\ "proxyDirectoryId": "IDPROXY",\ "displayOrder": 2\ },\ {\ "addressTypeId": "IDMBNO",\ "countries": [\ "ID"\ ],\ "code": "MBNO",\ "proxyDirectoryId": "IDPROXY",\ "displayOrder": 1\ }\ ] } [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#toc163730913) 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. #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#toc163730914) 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`](https://docs.nexusglobalpayments.org/messaging-and-translation/message-acmt.023-identification-verification-request) proxy resolution request. [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#toc163730915) 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`. [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#toc163730916) 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). [PreviousList of PSPschevron-left](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/list-of-psps) [NextProxy & Account Resolution Processchevron-right](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/proxy-and-account-resolution-process) Last updated 17 days ago * [Address types](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#address-types) * [Example address inputs](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#toc163730913) * [Account Identification](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#toc163730915) * [Example IBAN](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs/examples#toc163730916) Copy { "addressTypeId": "SGMBNO", "inputs": [\ {\ "addressInputId": "SGINPT1",\ "attributes": {\ "name": "accountOrProxyId",\ "type": "tel",\ "pattern": "^\\+(?:[0-9] ?){6,14}[0-9]$",\ "placeholder": "+6581234567",\ "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"\ }\ }\ },\ {\ "addressInputId": "SGINPT2",\ "attributes": {\ "name": "addressTypeCode",\ "type": "hidden",\ "value": "MBNO",\ "required": true\ },\ "iso20022Path": {\ "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Prxy/Tp/Cd",\ "pacs008": null\ }\ }\ ] } Copy { "addressTypeId": "SGACCT", "inputs": [\ {\ "addressInputId": "SGINPT1",\ "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"\ }\ }\ },\ {\ "addressInputId": "SGINPT3",\ "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"\ }\ }\ },\ {\ "addressInputId": "SGINPT2",\ "attributes": {\ "name": "addressTypeCode",\ "type": "hidden",\ "value": "ACCT",\ "required": true\ },\ "iso20022Path": {\ "acmt023": null,\ "pacs008": null\ }\ }\ ] } Copy { "addressTypeId": "GBIBAN", "inputs": [\ {\ "addressInputId": "GBINPT1",\ "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"\ }\ ]\ }\ },\ {\ "addressInputId": "GBINPT3",\ "attributes": {\ "name": "addressTypeCode",\ "type": "hidden",\ "value": "IBAN",\ "required": true\ },\ "iso20022Path": {\ "acmt023": null,\ "pacs008": null\ }\ }\ ] } --- # Address Types & Inputs | Nexus Payments Docs 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_ [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730910) 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) circle-exclamation 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). #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730911) 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”). ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730912) 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. ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730913) 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. #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730914) 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. #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730915) 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`. #### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730916) 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. ### [hashtag](https://docs.nexusglobalpayments.org/addressing-and-proxy-resolution/address-types-and-inputs#toc163730917) 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 `