Part of the FX Service. Used by PSPs.
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.
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.
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.
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.
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.
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.
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:
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.
Name | Type | Description |
---|---|---|
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
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)
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.