Processing proxy lookup requests

How proxy information is used in a Nexus payment flow

The following flow is described in more detail (with visual examples) in Steps 7-9: Addressing, Proxy & Confirmation of Payee:

  1. When the Sender selects the Destination Country for a payment, the Source PSP will call the GET /proxyschemes/{countrycode} API operation, specifying the country code. Nexus will respond with a full list of proxy schemes for that country (see example above).

  2. Nexus will show the Sender a form allowing them to select one of the possible proxy types and enter the proxy details.

  3. The Source PSP’s app must validate that the proxy details entered by the Sender is in the correct format. These validation rules will be provided as regular expressions in the proxy scheme definition provided by Nexus. The allows the PSP to validate the format in the app, without communication with Nexus or the proxy scheme.

  4. Once the Sender has provided the proxy details, the Source PSP will use the POST /creditorrequests API operation to send the information to Nexus.

  5. The Nexus Gateway will send the data to the associated proxy lookup service in the Destination Country.

  6. The proxy service will map the data and return any associated account details, or a negative response if the proxy is not linked.

Receiving proxy lookup requests from Nexus

Proxy lookup message (acmt.023)

Nexus will send a proxy lookup request to the PLSO formatted as an ISO 20022 acmt.023 (IdentificationVerificationRequestV03) message.

The PLSO must be able to accept the message in this format. If the domestic proxy lookup message format is different, the PLSO is responsible for translating the message from the Nexus acmt.023 to the domestic format message.

The Nexus acmt.023 has the following features:

  • The proxy provided by the Sender should be included in the Verification > PartyAndAccountIdentification > Proxy element:

    • Type should include the ISO 20022 ExternalProxyAccountType1Code (eg MBNO) for the proxy type that was selected by the Sender

    • Identification should include the actual proxy text provided by the Sender

  • To allow the Proxy Lookup Service Operator to guard against phishing (eg entering phone numbers into a Nexus-enabled app in order to get the corresponding account holder names), the field Assignment > Creator > Party > Identification > Private Identification > Identification should include a unique ID that uniquely identifies the Sender. This ID may be a official ID (eg National Identity Number) or a generated hash value that will be reused for all requests from this Sender. The PLSO can use this value to rate-limit the number of requests coming from a particular Sender.

Responding to proxy lookup requests

Response message (acmt.024)

The PLSO must respond to Nexus with an acmt.024 message. The PLSO is responsible for any translation required to convert from the domestic format to the Nexus acmt.024.

Minimum data to be returned by the proxy lookup service

If the proxy successfully maps to an account, the proxy lookup service should return, at a minimum:

  • 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), a partially obscured name or a nickname defined by the user, depending on the proxy service.

    • This value should be in the element UpdatedPartyAndAccountIdentification > Account > Name

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

  • the PSP identifier (eg BIC) and account identifier of the linked account

Note that wherever possible, the full real name should be returned, as this information supports accurate and automated sanctions screening. Where the real name is not returned, the Source PSP must instead try to retrieve that information by (a) sending a Request for Information to the Destination PSP, although many PSPs will not support the RFI process, or (b) asking the Sender for this information, which may introduce inaccurate data, typos etc.

Inactive or unregistered proxies

If the proxy is not registered or has been deactivated, the PSLO should respond with:

  • the /PrxyLkUpRspn/LkUpRspn/PrxyRspnSts/ element set to RJCT

  • the /PrxyLkUpRspn/LkUpRspn/PrxyRspnSts/StsRsnInf/Rsn/Cd/ element set to a valid ExternalStatusReason1Code from the ISO 20022 External Code Set (available at Typically only BE23 would be applicable:

Table: Proxy Lookup – Reject Status Reasons

The following codes are from the ISO 20022 External Code Set, available at






Phone number or email address, or any other proxy, used as the account proxy is unknown or invalid.

Using the Nexus APIs

The IPSO can use the Nexus administration portal to update information about the proxy lookup schemes. Alternatively the IPSO can use the relevant APIs to submit this information.

Last updated