Quotes

Part of the FX Service. Used by PSPs.

Get all quotes for a specific corridor

As soon as Sender has selected the Destination Country for the payment and entered the Source Currency Amount or Destination Currency Amount, the PSP can call the Quotes API.

Because some countries have instant payment systems that operate in more than one currency, both the currencies and the countries must be specified in the API call.

The PSP must also specify (using the amt and amtCcy query parameters) either:

• The Source Currency Amount that should be debited from the Sender’s account, or

• The Destination Currency Amount that should be credited to the Recipient’s account

The PSP should also provide their PSP Id (typically BIC) so that Nexus can calculate if each FXP provides any discount (PSP-based improvement) for that PSP.

Return a list of quotes for a specific currency pair

GET https://local.nexus.gateway/api/v1/quotes/{srcCtry}/{srcCcy}/{destCtry}/{destCcy}/

This will return the list of quotes for a specific currency pair. Nexus will automatically apply any improvements that each FXP provides to the requesting Source PSP, as well as any improvements that apply based on the value of the payment.

Path Parameters

Name	Type	Description
srcCtry*	String	Source Country, ISO 3166 alpha-2
srcCcy*	String	Source Currency, ISO 4217 alpha-3
destCtry*	String	Destination Country, ISO 3166 alpha-2
destCcy*	String	Destination Currency, ISO 4217 alpha-3

Query Parameters

Name	Type	Description
amt*	String	Value of the payment as defined by the sender (decimal)
amtCcy*	String	Currency of the payment as defined by the Sender, ISO 4217 alpha-3
pspIdType*	String	Type of PSP Id: BIC, LEI or Other
pspId*	String	Id of PSP
limit	String	Number of quotes to retrieve (if not default)

200: OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<QtsRspn xmlns="https://nexus.bisih.org/nexus.fxqt.001.001.01">
 <GrpHdr>
    <MsgID>ITEURSGSGD20230124225706257</MsgID>
    <CreDtTm>2023-01-24T22:57:06.257Z</CreDtTm>
  </GrpHdr>
  <OrgnlGrpInf>
    <SrcCtry>IT</SrcCtry>
    <UnitCcy>EUR</UnitCcy>
    <DstnCtry>SG</DstnCtry>
    <QtdCcy>SGD</QtdCcy>
    <OrgnlInstdAmt Ccy="SGD">100</OrgnlInstdAmt>
  </OrgnlGrpInf>
  <QtRspn>
    <RspnSts>ACTC</RspnSts>
  </QtRspn>
  <Qts>
    <Qt>
      <QtID>05201109-1cf1-42ba-b661-32d9f6bc8b63</QtID>
      <FXPId>
        <BICFI>NEXUITMMSAP</BICFI>
      </FXPId>
      <FXPNm>ITFX1</FXPNm>
      <XchgRate>1.6634</XchgRate>
      <SrcUPSId>EURTIPS</SrcUPSId>
      <DestUPSId>SGDFAST</DestUPSId>
      <AdjSrcAmt Ccy="EUR">60.12</AdjSrcAmt>
      <AdjDstnAmt Ccy="SGD">100</AdjDstnAmt>
    </Qt>
    <Qt>
      <QtID>2d0e8ea2-41d2-4d4a-8080-c2f8c80f1b5a</QtID>
      <FXPId>
        <BICFI>NEXUITXXSAP</BICFI>
      </FXPId>
      <FXPNm>ITFX2</FXPNm>
      <XchgRate>1.6501</XchgRate>
      <SrcUPSId>EURTIPS</SrcUPSId>
      <DestUPSId>SGDFAST</DestUPSId>
      <AdjSrcAmt Ccy="EUR">60.60</AdjSrcAmt>
      <AdjDstnAmt Ccy="SGD">100</AdjDstnAmt>
    </Qt>
  </Qts>
</QtsRspn>

The GET /quotes/ API automatically applies any tier-based or PSP-based improvements, and checks the maximum value of a payment through both IPSs, adjusting the payment value automatically if necessary. Each steps is described in more detail below.

Tier-based improvements

In Nexus a specific FXP can offer better rates for larger transactions. This works as follows:

• For each specific Source Currency, an FXP can define a number of “tiers” at which better rates apply.

• For each tier, the FXP will define how much the base rate (as provided in the POST /rates/ API) should be improved, in basis points.

Tier-based improvements are offered to all PSPs and will be automatically applied by Nexus before the quotes are returned to the PSP. See Tier-based improvements for further detail.

PSP-based improvements

FX Providers may also want to offer better rates to specific PSPs, for example, PSPs that are already customers of the FXP. In Nexus this works as follows:

• An FXP can define the PSPs to which it wishes to offer improved rates

  • For each PSP, the FXP can define how much the base rate should be improved, in basis points.

• When a Source PSP calls the GET /quotes/ API, Nexus will check whether any FXPs have registered improvements for that PSP and apply the improvement to the FXP's base rate.

• An FXP does not need to set any PSP-based improvements. If no PSP-based improvement is set for a specific PSP, the base rate will apply.

Any PSP-specific improvements are set through a bilateral agreement with the PSP and FXP, outside of the Nexus scheme. See PSP-based improvements for further detail.

Caps on the maximum transaction value

Some instant payment systems set limits on the maximum size of a transaction which can be sent. An IPS may also set a lower limit on cross-border payments through Nexus than on domestic transactions.

If the PSP were to send a transaction that exceeded the maximum value of either the Source or Destination IPS, it will be rejected by that IPS. To avoid this, Nexus will validate that the Source Currency Amount and Destination Currency Amounts do not exceed the maximum value in each IPS before returning the list of quotes. This is done as follows:

• For each rate in the quotes response, Nexus will calculate if either the Source Currency Amount or Destination Amount Currency Amount exceeds the relevant IPS’s MaxValue

  • If so, Nexus will calculate the maximum value (in both Source and Destination Currency Amounts) which can actually be sent

  • This information will be returned in the quotes list in “AdjustedSourceAmount” and “AdjustedDestinationAmount” fields

  • If the value of the payment is capped at a lower value than the Sender requested, the response for any adjusted rates will include the AdjustedReason element, which will inform the PSP whether the Source IPS Max Value or Destination IPS Max Value (or both) was exceeded.

    • The Source PSP should also inform the Sender that the amount they requested was above the relevant limits and has been adjusted accordingly.

Using the response to selecting a preferred quote

The Source Gateway returns a list of all quotes available for that currency pair, ordered from best to worst (ie. sorted by rate in descending order). Each quote includes the following information:

TABLE: Quote Structure

ELEMENT	USAGE
Quote Id	To be referenced in the final payment instruction
FXP Financial Institution Identifier	The financial institution identifier (BIC or LEI) of the FX Provider
Rate	A specific FX Rate (where Source Amount * Rate = Destination Amount). This rate will include any tier-based or PSP-based improvements.
Source IPS Id	The ID of the IPS where the FXP is able to receive funds
Destination IPS Id	The ID of the IPS from which the FXP is able to pay out funds
Adjusted Source Amount	If Sender specified the Destination Amount, this shows the value of (Destination Amount ÷ Rate) If the Sender specified the Source Amount, this will show the amount specified by the Sender unless the amount has been reduced by Nexus due to maximum values on either the Source or Destination IPS.
Adjusted Destination Amount	If Sender specified the Source Amount, this shows the value of (Source Amount * Rate) If the Sender specified the Destination Amount, this will show the amount specified by the Sender unless the amount has been reduced by Nexus due to maximum values on either the Source or Destination IPS.

The Source PSP is responsible for selecting the FX Provider and quote that the PSP wishes to use. The PSP does not need to show the list of quotes to the Sender.

The PSP must store the Quote ID of the preferred quote in memory as the PSP will need to use it when setting up the payment instruction.