Proxy Schemes & Formats

Part of the Proxy Service. Used by PSPs.

Get the list of proxy formats for a specific country

When a Sender has selected the Destination Country, the PSP can use the GET /countries/{country_code}/proxyschemes API operation to retrieve the list of proxy schemes and proxy formats available in that country.

Get all proxy schemes for a specific country

GET https://local.nexus.gateway/api/v1/countries/{countryCode}/proxyschemes

Path Parameters

Name	Type	Description
countryCode*	String	ISO 3166 alpha-2 country code

200: OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PrxySchmes xmlns="https://nexus.bisih.org/nexus.001.001.01">
  <PrxySchme>
    <OprtngCtrys>
      <Ctry>SG</Ctry>
    </OprtngCtrys>
    <EffctvDtTm>2023-01-24T00:00:00.000Z</EffctvDtTm>
    <SchmeNm>PAYNOW</SchmeNm>
    <PrxyFmts>
      <Prxy>
        <PrxyTp>MBNO</PrxyTp>
        <PrxyExmpl>[phone]</PrxyExmpl>
        <PrxyFmt>^\+65\d{8}$</PrxyFmt>
        <PrxyDesc>Any Singaporean mobile number</PrxyDesc>
      </Prxy>
      <Prxy>
        <PrxyTp>NIDN</PrxyTp>
        <PrxyExmpl>640829075377</PrxyExmpl>
        <PrxyFmt>^\d{12}$</PrxyFmt>
        <PrxyDesc>Any Singaporean company/individual government ID</PrxyDesc>
      </Prxy>
      <Prxy>
        <PrxyTp>CINC</PrxyTp>
        <PrxyExmpl>T09LL0001B</PrxyExmpl>
        <PrxyFmt>^[A-Za-z0-9]{9,10}$</PrxyFmt>
        <PrxyDesc>Unique Entity Number (UEN)</PrxyDesc>
      </Prxy>
    </PrxyFmts>
  </PrxySchme>
</PrxySchmes>

The GET /api/v1/countries/{country_code}/proxyschemes response lists:

• all proxy schemes available in the Destination Country and

• the proxy formats available in each scheme.

Individual proxy formats

The Proxy Type in Nexus is taken from the ISO 20022 External Code Set (available at www.iso20022.org) using the values from ExternalProxyAccountType1Code. For commonly used proxy types, see

Generating the addressing options form

The ProxyType (PrxySchmes/PrxySchme/ProxyFmts/Prxy/PrxyTp), and ProxyDescription (PrxySchmes/PrxySchme/PrxyFmts/Prxy/PrxyFmt) fields can be used to automatically generate the addressing options form as shown below

Generating the proxy details form

When the Sender has selected a preferred address format, they should be shown the field to input a specific proxy.

If a proxy is selected, the PrxySchmes/PrxySchme/PrxyFmts/Prxy/PryExmpl and PrxySchmes/PrxySchme/PrxyFmts/Prxy/PrxyFmt elements can be used here:

• Proxy Example = the example content shown in field before the user enters any information (ie the “placeholder” attribute on a HTML form element)

• Proxy Format = the regular expression that can be used for client-side validation of the proxy provided by the Sender

If a local account number is selected, then the PSP will need to display a form that provides two input fields: one for the local PSP identifier (eg BIC) and one for the local account number.

• The correct format for the PSP identifier is found in UPSs/UPS/PSPIdFmt

• The correct format for the PSP identifier is found in UPSs/UPS/LclAcctId/LclAcctFmt

Issuing a proxy lookup request

The provided proxy should be embedded in an acmt.023 message and submitted to Nexus using the POST /creditorrequests/ API operation. See Creditor Requests API for details.

Reasons for Proxy Lookup Failure

The table below shows the action to be taken when the Creditor Info Request fails and what type of message could be shown to the Sender.

STAGE & FAILURE REASON	EXAMPLE SCENARIO	ERROR MESSAGE RETURNED BY NEXUS
Proxy Conversion: Proxy is not linked to an account	The Sender assumes that they can send a payment using the Recipient’s phone number, but the Recipient hasn’t linked this number to a PSP account.	“No matching element was found”
Payment: Destination PSP not enabled to receive Nexus payments	The Destination PSP has not yet made the necessary changes to accept payments through Nexus, for example connecting their sanctions screening software.	“PSP of creditor account holder not reachable”
All Stages: Non-unique Message ID	The Source PSP sends the identical message with the equivalent content twice.	“Invalid message ID: XXX”