Part of the FX Service. Used by FXPs.
Nexus provides three APIs to FX Providers:
POST /rates/
- to issue new rates
POST /improvements/tiers/
- to register or update a tier-based improvement for a specific currency
POST /improvements/psps/
- to register or update an improvement for a specific PSP
In a production system, APIs would also be provided to allow to see FXP to “delete” or withdraw PSP-based and tier-based improvements. Rates could be withdrawn / expired by an FXP, but this is equivalent to the FXP exiting the market and should only be used in certain circumstances.
An FXP will submit a new rate using the Rates
API. Note: FXPs cannot update existing rates; instead they simply submit a new rate that takes effect immediately.
POST
https://local.nexus.gateway/api/v1/rates
When processing the rate update request, Nexus will:
validate the request (by checking that the FX Provider is set up to rate for that currency pair and has nominated validated Settlement Account Providers in both the Source and Destination Country)
save the new rate in the rates table
set any existing rates for this FXP-corridor combination to expire immediately
retrieve any tier-based improvements set by the FXP for this Source Currency
for each tier, calculate the improved rate
save a new rate in the rates table with the threshold defined in this tier and the new improved rate
The new rate is immediately shown to Source PSPs when they use the GET /rates/
API (alongside rates for that corridor from other FXPs).
POST /rates/
The Nexus Gateway will send a response message to the FX Provider to confirm that a rate has been successfully accepted and saved. The response message includes the newly created quote.
The response message also includes the current best available rate on the market (but not the identity of the FX Provider offering that rate). This allows each FX Provider to see whether the rates they offer are competitive, and to adjust those rates if necessary.
FXPs are NOT permitted to use the GET Rate API to see the full list of rates offered by their competitors; this will be enforced by both API permissions and the Nexus scheme rulebook.
FXPs can set tier-based improvements using the API:
POST
https://local.nexus.gateway/api/v1/tier_improvements
Allows an FXP to set a new tier improvement for a specific Source Currency
Each tier-based improvement must specify:
FXP Id – the FXP offering the improvement
UnitCcy – the Source Currency to which the improvement applies. (Tier-based improvements are always based on the Source Currency, not the Destination Currency)
Threshold – the smallest amount, in the Source Currency, at which the improvement rate applies. The Source Currency Amount of the payment must be greater than or equal to the threshold.
Improvement – a rate of improvement, recorded in basis points, which should be applied to the base rate.
For transaction values below the lowest threshold, the base rate provided by the FXP in POST /rates/
applies.
APIs to delete or “revoke” tier-based improvements have not yet been built and would need to be added to a production version.
FXPs can improvements for specific PSPs using the API below.
PSP-specific improvements are additional to any tier-based improvements. (Nexus calculates relevant tier-based improvements first, then applies any PSP-based improvements.)
A PSP-specific improvement needs to specify:
FXP Id – the FXP offering the improvement to a PSP
PSP Id – the PSP to which the improvement is being offered
Improvement – the improvement, in basis points, which should be applied to any rate offered by this PSP.
POST
http://local.nexus.gateway/api/v1/psp_improvements
Alllows an FX Provider to post a new improvement for a specific PSP. The improvement will apply to all quotes issued to that PSP, for all currencies that the FXP offers.
APIs to delete or “revoke” PSP-specific improvements have not yet been built.
Whenever Nexus successfully processes a payment (ie. receives a pacs.002 with a “ACCC” status code from the Destination IPS), it will send a notification to FX Provider whose rate was referenced. This notification should be used by the FXP to update its internal records of the balances of all its settlement accounts.
The FXP will provide the API endpoints or message queue to which these notifications should be sent during technical onboarding to Nexus.
This notification is structured as an ISO 20022 fxtr.017
message. The key elements of the fxtr.017 are described below:
A production version of Nexus would also include the ability for FXPs to generate aggregate reports on all transactions for which they provided FX in a certain time period. These reports would also include a breakdown of the calculation of the final rate, showing how the base rate, any tier improvements and any PSP improvements were applied to each quote. This functionality has not yet been built.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
unitCcy*
String
The Source Currency (ISO 4217 alpha-3)
qtdCcy*
String
Destination Currency (ISO 4217 alpha-3)
rate*
String
Decimal, 4 decimal places
srcUPS
String
The Source UPS where the FXP holds an account (either directly or via a SAP)
dstUPS
String
The Destination UPS where the FXP holds an account (either directly or via a SAP)
unitCcy*
String
Source Currency to which this tier improvement applies
threshold*
String
Minimum value at which a payment will qualify for this tier improvement (Payment must be equal or greater than the threshold)
improvement
String
Improvement to add to the base rate in basis points
fxpId*
String
pspIdType
String
BIC, LEI or Other
pspId
String
Id of the PSP
improvement
String
Improvement in basis points to add to the base rate
ISO 20022 fxtr.017 ELEMENT
MEANING
OriginatorReference
ID of the underlying Nexus payment that made use of the FXP’s quote
CommonReference
ID of the quote issued by Nexus to the PSP
ProductType
“Nexus”
TradingSideIdentification
SubmittingParty
BIC of the Source PSP
CounterpartySideIdentification
SubmittingParty
BIC of the FXP
TradeAmounts
TradingSideBuyAmount
Amount in target/destination currency that was transferred from the FXP’s account to the Destination PSP via the Destination IPS
TradingSideSellAmount
Amount in source currency that the Source PSP paid to the FXP’s account via the Source IPS
AgreedRate
ExchangeRate
Exchange rate applied (from the original quote, after any tier-improvements or PSP-based improvements have been added)
UnitCurrency
Source Currency
QuotedCurrency
Destination/Target Currency
TradingSideSettlementInstructions
DeliveryAgent
BIC of the Destination Settlement Account provider and the account number of the FXP’s account at the SAP
ReceivingAgent
BIC of the Destination PSP
CounterpartySideSettlementInstructions
DeliveryAgent
BIC of the Source PSP
ReceivingAgent
BIC of the Source Settlement Account Provider and the account number of the FXP’s account at the SAP