Executable Rates Guide
Give Feedback
TxB APIs allows TxB clients to make FX payments as described on the Make a Payment Guide. Additionally, this guide describes how to lock in an exchange rate before actually sending the payment. This can be useful if you want to display a proposed FX rate to your customer before committing them to accepting the rate, or do a bulk purchase of your FX that can be allocated to multiple underlying payments. All exchange rates described below are spot transactions (T+2). Rates are only available during market opening and are valid for 90 seconds.
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 creating a quote, you must specify the payment amount, which is the amount of the currency you want to send as payment.
To create a quote,
POST /v2/exchangeRates/quotes with the following payload:
{
"fxTrade": {
"paymentCurrency": "EUR", // The currency you want to convert to
"sourceCurrency": "USD", // The currency you will convert from
"paymentAmount": 1000
},
"liquidityTiming": {
"tenor": "90_SECONDS"
}
}Returns this response:
{
"quoteId": "Q7471",
"tradeId": null,
"status": "QUOTED",
"relatedEntityId": null,
"expirationTime": "2023-02-21T20:46:23.162Z",
"liquidityTiming": {
"settlementDate": null,
"tenor": "90_SECONDS"
},
"fxTrade": {
"paymentAmount": 1000.00,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 1066.29,
"fxRate": 1.06628522,
"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 within 90 seconds
- Walk away and 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,
POST /v2/exchangeRates/quotes/accept
{
"quoteId": "Q7471"
}Returns this response:
{
"quoteId": "Q7471",
"tradeId": "271130",
"status": "TRADED",
"relatedEntityId": null,
"expirationTime": null,
"liquidityTiming": {
"settlementDate": “2023-02-23”,
"tenor": null
},
"fxTrade": {
"paymentAmount": 1000.00,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 1066.29,
"fxRate": 1.06628500,
"fxTimeStamp": null
},
"fxTradeUsage": {
"paymentAmountAvailable": 1000.00,
"sourceAmountAvailable": 1066.29,
"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 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 you cache in your system about your trade is always accurate.
Request quote details by:
POST /v2/exchangeRates/quotes/status
{
"idType": "TRADEID",
"idValue": "271130"
} Returns this response:
{
"quoteId": "Q7471",
"tradeId": "271130",
"status": "TRADED",
"relatedEntityId": null,
"expirationTime": null,
"liquidityTiming": {
"settlementDate": “2023-02-23”,
"tenor": null
},
"fxTrade": {
"paymentAmount": 1000.00,
"paymentCurrency": "EUR",
"sourceCurrency": "USD",
"sourceAmount": 1066.29,
"fxRate": 1.06628500,
"fxTimeStamp": null
},
"fxTradeUsage": {
"paymentAmountAvailable": 1000.00,
"sourceAmountAvailable": 1066.29,
"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.
To initiate your payment,
POST /v2/payments/payouts
{
"paymentRequestId": "US_004535424",
"requestLevel": {
"fundingSource": {
"fundingAccount": {
"accountInfo": {
"accountHolderName": "Client11",
"accountIdentifier": {
"accountNumber": "290000069300"
},
"bankIdentifier": {
"bic": "GSCRUS30XXX"
}
}
},
"fundingCurrency": "USD"
},
"routingPreferences": {
"paymentTypePreference": "WIRE"
}
},
"payouts": [
{
"paymentEndToEndId": "EUR_031434",
"corePayoutInfo": {
"requestedPaymentDate": "2023-02-21",
"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": "271130"
}
}
}
]
}For a successful payment request, you will get the response:
{
"paymentRequestId": "004535424",
"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.
Frequently Asked Questions
| Question | Answer |
|---|---|
| When I accept my quote, the status shows PENDING, not QUOTED. How come? | If you receive the status PENDING, poll the Get Trade details API from Step 3 (POST /v2/exchangeRates/quotes/status) until status shows TRADED. PENDING status simply means that we haven’t booked the trade yet. |
| Is there a separate payment date? | Once you accept a quote and receive a Trade Id, you have 2 business days to instruct payments. This deadline is expressed as settlementDate in your quote acceptance response. |
| Is there a difference between payment value date and deal settlement date? | The payment date is when the payment is settled. The deal settlement date is the date by which you should initiate the payment. Payments can be made up to T+2 days once you accept a quote. |
| What happens when the settlementDate is passed and no payments are sent? | You have up to T+2 to instruct payments using POST /v2/payments/payouts from Step 4. Once T+2 has passed, our Operations team will initiate an unwind process with you. This is a manual process that we will manage and support you through. However, these breaks are not common. |
| Can you support weekend trading? | Currently, we do not support presenting quotes over the weekend. Our executable rates product is only available during open market hours. Any trade submitted after 5pm ET on Friday will be rejected. Please discuss extending the offering to weekends with your TxB representative. We offer a held rates product which will allow you to provide quotes over the weekend. |
| Can I use the same trade across multiple unassociated legal entities? | We do not support settlement across multiple entities. We currently only support settlement for a single client, within a single branch. |
Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.