Held FX Rates
TxB APIs allows TxB clients to make FX payments as described on the Make a Payment Guide. You can also find our Executable FX Rates Guide that describes how to lock in an exchange rate before actually sending the payment. This guide describes how to lock in an exchange rate for up to 72 hours before you know your total trade amount, allowing you to extend the settlement window from quote to T+5.
Step by Step Guide
Step 1 - Create an exchange rate quote
First, create a quote. This quote is real-time (it changes throughout the day) and includes all relevant FX fees that you have agreed with TxB.The payment using the FX will likely generate additional fees.When retrieving your FX quote, you need to specify it’s duration. Your options are 24, 36, 48 or 72 hours.
To create a quote, use this API
POST /v2/exchangeRates/quotes
{
"fxTrade": {
"paymentCurrency": "EUR",
"sourceCurrency": "USD"
},
"liquidityTiming": {
"tenor": "72_HOURS"
}
}Returns this response:
{
"quoteId": "Q7589",
"tradeId": null,
"status": "QUOTED",
"relatedEntityId": null,
"expirationTime": "2023-02-24T22:00:00Z",
"liquidityTiming": {
"settlementDate": null,
"tenor": "72_HOURS"
},
"fxTrade": {
"paymentAmount": 1896615.00,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 2004524.50,
"fxRate": 1.05689584,
"fxTimeStamp": null
},
"fxTradeUsage": null,
"fxQuoteUsage": null
}Step 2 - Decide whether to accept the rate
Now that you created a quote, you can:
- Book a trade against the quote by accepting it before it expires
- Leave the quote to expire
- Request a new quote
If you decide to accept the quote, you have up to 2 business days to make a payment(s) on that trade.
To accept the quote, use this API
POST /v2/exchangeRates/quotes/accept
{
"paymentAmount": 100,
"quoteId": "Q7589",
"tradeRequestId": "tradeid0004"
}Returns this response:
{
"quoteId": "Q7589",
"tradeId": "272430",
"status": "TRADED",
"relatedEntityId": null,
"expirationTime": null,
"liquidityTiming": {
"settlementDate": "2023-02-28",
"tenor": null
},
"fxTrade": {
"paymentAmount": 100.00,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 105.69,
"fxRate": 1.05689584,
"fxTimeStamp": null
},
"fxTradeUsage": {
"paymentAmountAvailable": 100.00,
"sourceAmountAvailable": 105.69,
"linkedPaymentEndToEndIds": null
},
"fxQuoteUsage": null
}At this point, the currency is now TRADED. Canceling the trade would involve booking an equal and opposite trade which may create a financial loss if rates have changed in an unfavorable direction.
Step 3 - View the current status of the quote or trade
Use this API to get information about your quote or trade. This API will help you know the details of your trade, including trade status, how much of your trade has been utilized and what payments are associated with it. It will help you ensure that the data that the cache in your system about your trade is always accurate.
When you poll for your quote ID, you’ll receive a list of all associated trade IDs. when you poll for your trade ID, you’ll receive a list of associated payment IDs.
POST /v2/exchangeRates/quotes/status
{
"idType": "QUOTEID",
"idValue": "Q7589"
}Returns this response:
{
"quoteId": "Q7589",
"tradeId": null,
"status": "QUOTED",
"relatedEntityId": null,
"expirationTime": "2023-02-24T22:00:00Z",
"liquidityTiming": null,
"fxTrade": {
"paymentAmount": 1896615.00,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 2004524.50,
"fxRate": 1.05689584,
"fxTimeStamp": null
},
"fxTradeUsage": null,
"fxQuoteUsage": {
"paymentAmountAvailable": 1896515.00,
"sourceAmountAvailable": 2004418.81,
"linkedTradeIds": [
"272430"
]
}
}In case of trade details, the request would look like:
POST /v2/exchangeRates/quotes/status
{
"idType": "TRADEID",
"idValue": "272430"
}Returns this response:
{
"quoteId": "Q7589",
"tradeId": "272430",
"status": "TRADED",
"relatedEntityId": null,
"expirationTime": null,
"liquidityTiming": {
"settlementDate": "2023-02-28",
"tenor": null
},
"fxTrade": {
"paymentAmount": 100.00,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 105.69,
"fxRate": 1.05689584,
"fxTimeStamp": null
},
"fxTradeUsage": {
"paymentAmountAvailable": 100.00,
"sourceAmountAvailable": 105.69,
"linkedPaymentEndToEndIds": []
},
"fxQuoteUsage": null
}Step 4 - Use your currency
You have two business days to use your newly purchased currency to make a payment. You can use the entire amount in one payment or divide it across multiple payments. Any currency that is unused after two days will be unwound. An unwind may create a financial loss if rates have changed in an unfavorable direction.
To make a payment, include the tradeId in your request. Your payment amount should not exceed the total trade amount.
POST /v2/payments/payouts and include your tradeId in the payouts object.
{
"paymentRequestId": "US_0045724",
"requestLevel": {
"fundingSource": {
"fundingAccount": {
"accountInfo": {
"accountHolderName": "Client11",
"accountIdentifier": {
"accountNumber": "290000069300"
},
"bankIdentifier": {
"bic": "GSCRUS30XXX"
}
}
},
"fundingCurrency": "USD"
},
"routingPreferences": {
"paymentTypePreference": "WIRE"
}
},
"payouts": [
{
"paymentEndToEndId": "EUR_0314734",
"corePayoutInfo": {
"requestedPaymentDate": "2023-02-24",
"paymentCurrency": "EUR",
"amount": 100.00,
"payeeAccount": {
"accountInfo": {
"accountHolderName": "Creditor Acc",
"accountIdentifier": {
"iban": "GB46BUKB20041538290008"
},
"bankIdentifier": {
"bic": "BUKBGB22"
},
"address": {
"addressLines": [
"15",
"Broad Avenue"
],
"city": "Amsterdam",
"countryISOCode": "NL",
"postalCode": "1011 AA"
}
}
},
"messagesFromOriginator": {
"paymentPurpose": "WIRE TEST-EUR",
"remittanceInfo": {
"unstructuredRemittance": [
"WIRE TEST-EUR"
]
}
}
},
"routingSpecificPayoutInfo": {
"wirePayoutLevel": {
"chargeBearer": "SLEV"
}
},
"otherPayoutInfo": {
"fxPayoutLevel": {
"amountType": "PAYMENT",
"tradeId": "272430"
}
}
}
]
}For a successful payment request, you will get the response:
{
"paymentRequestId": "US_0045724",
"collectionRequestId": null,
"requestStatus": "ACCEPTED",
"message": null
}Once you’ve initiated a payment, review the status of your trade again to see how much currency you have left to use.
Use POST /v2/exchangeRates/quotes/status as mentioned in Step 3 above to get the Trade details.
Step 5 - Troubleshoot your issues
While using our FX APIs, you may encounter exceptions and it is important that you build a workflow to manage those.
| Exception Scenario | Comments |
|---|---|
| Quote expired | Your QuoteId has expired. Please request a new quote using /v2/exchangeRates/quotes. |
| Invalid quote ID | Your Quote ID is invalid. Please check your quote ID and resubmit. |
| Invalid trade ID | Your Trade ID is invalid. Please check your Trade ID and resubmit. |
Invalid request parameters on any of the following
| Invalid request parameters on any of the following
|
| Invalid currency – Request a new quote API | This currency is not offered for Held Rates. Please resubmit using a valid currency. |
| Quote/Trade quantity exceeds max control notional limit | The quote/trade quantity exceeds the maximum limit. Please resubmit using a valid limit or contact your GS representative. |
| Client markup not available | Client markup not available Request could not be completed. Please contact your GS representative. |
Liquidity sources unavailable when using
|
|
| Trade on a quote is rejected | Your request could not be completed. Please reach out to your GS representative. |
| Request failed for unknown reasons | Technical Error. Please raise an internal alert and contact your GS representative. |
| Quote request not completed in time | Technical Error. Please resubmit your request. |
| Trade request exceeds the notional remaining for that quote | Your trade quantity requested exceeds the available quote limit. Please resubmit with a valid quantity. |
Client preferences not set
| If you do not define a max held rate notional, default limits will take effect.If this error persists, please contact your GS representative. |
Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.