Rates

Part of the FX Service. Used by FXPs.

Using the Nexus APIs

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.

Posting a new rate

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 a new rate

POST https://local.nexus.gateway/api/v1/rates

Request Body

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)

201: Created

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fxpId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "unitCcy": "string",
    "qtdCcy": "string",
    "rate": 1.5000,
    "sourceUPS": "string",
    "destUPS": "string",
    "marketRate": 1.5020
  }
]

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

Response to 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.

Setting tier-based improvements for larger transactions

FXPs can set tier-based improvements using the API:

Post a new tier improvement

POST https://local.nexus.gateway/api/v1/tier_improvements

Allows an FXP to set a new tier improvement for a specific Source Currency

Request Body

Name	Type	Description
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

201: Created

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "unitCcy": "SGD",
    "threshold": 50000.00
    "improvement": 50,
    "fxpId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]

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.

Setting PSP-based improvements for specific PSPs

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 a new PSP improvement

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.

Request Body

Name	Type	Description
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

201: Created

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "fxpId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pspIdType": "BIC",
    "pspId": "CCCCSGCC",
    "improvement": 100
  }
]

APIs to delete or “revoke” PSP-specific improvements have not yet been built.

Receiving notifications of completed payments

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:

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

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.