Exchanges
Overview
Exchanges enable users to retrieve exchange rate quotes as well as exchange money quickly, easily and securely. Exchanges have two separate phases. The first phase is the retrieval of a quote. This step enables users to view the rate of exchange and determine whether it is acceptable. The second step is to accept and confirm said quote. The quote is only valid for a specific timeframe (typically 30 seconds). In the event that the allotted time expires, the client must then re-quote to get a new valid rate. The value date and the settlement date of the exchange are calculated according to each currency's cut-off times and holidays by our system. This may vary per connected Service Provider.
To be able to create an exchange the account from which the currency will be sold/debited needs to contain the requisite amount to cover the cost before the Settlement Date. If the balance is not enough to complete the exchange (and if applicable the associated fees) then the system rolls the settlement date to the next available settlement date. In addition, while doing this, it also increments the roll count. A User can see that number if they call the 'Get Exchange Request' with a 'rollCount' parameter.
Quote a rate
To be able to retrieve a quote, the client has to have an active account for both currencies.
POST /exchange-quotes
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"clientId": "00000000-0000-0000-0000-000000000000",
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 10000
},
"pricing": {
"markupDefinition": {
"type": "ratio",
"ratio": "0.005"
}
}
},
"connect": {
"type": "implicit"
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "fee-and-markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"clientId": "00000000-0000-0000-0000-000000000000",
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 10000
},
"pricing": {
"markupDefinition": {
"type": "ratio",
"ratio": "0.005"
},
"feeDefinition": {
"type": "ratio",
"ratio": 0.005,
"boundaryCurrency": "GBP",
"minimumAmount": 12.00,
"maximumAmount": 100000.00
}
}
},
"connect": {
"type": "implicit"
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"clientId": "00000000-0000-0000-0000-000000000000",
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 10000
},
"pricing": {
"type": "ratio",
"ratio": "0.005"
}
},
"connect": {
"type": "implicit"
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "implicit"
}
},
"data": {
"quote": {
"clientId": "00000000-0000-0000-0000-000000000000",
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 10000
}
},
"connect": {
"type": "implicit"
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "fee-and-markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 1.234797985,
"buyCurrency": "EUR",
"buyAmount": 6.17,
"sellCurrency": "GBP",
"sellAmount": 5.00,
"feeAmount": 5.91,
"feeCurrency": "EUR",
"exchangeDate": "2022-04-27",
"expiryDateTime": "2022-04-27T20:49:27.909544",
"cutOffDateTime": "2022-04-27T23:55:00",
"settlementDate": "2022-04-27",
"offline": false,
"debitAmount": 5.00,
"creditAmount": 12.08
}
},
"connect": {
"type": "implicit",
"serviceProvider": "currencycloud"
},
"metadata": {}
}
Requote
If the client does not confirm the Exchange within the permitted time frame to send the Create Exchange transaction request then the quote must be refreshed. If so, the client will need the account for the quote ID which is received in the response of 'Create A Quote'.
POST /exchange-quotes/{quoteId}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"enabled": true,
"sourcingMethod": "explicit",
"chargingType": "markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"clientId": "00000000-0000-0000-0000-000000000000",
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 10000.00
},
"pricing": {
"type": "ratio",
"ratio": "0.005"
}
},
"connect": {
"type": "implicit"
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"enabled": true,
"sourcingMethod": "explicit",
"chargingType": "markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"clientId": "00000000-0000-0000-0000-000000000000",
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 10000.00
},
"pricing": {
"markupDefinition": {
"type": "ratio",
"ratio": "0.005"
}
}
},
"connect": {
"type": "implicit"
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"enabled": true,
"sourcingMethod": "explicit",
"chargingType": "fee-and-markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"clientId": "00000000-0000-0000-0000-000000000000",
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 10000.00
},
"pricing": {
"markupDefinition": {
"type": "ratio",
"ratio": "0.005"
},
"feeDefinition": {
"type": "ratio",
"ratio": 0.005,
"boundaryCurrency": "GBP",
"minimumAmount": 5.00,
"maximumAmount": 100000.00
}
}
},
"connect": {
"type": "implicit"
},
"metadata": {}
}
{
"workflow": {},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 1.147147353,
"buyCurrency": "EUR",
"buyAmount": 11.47,
"sellCurrency": "GBP",
"sellAmount": 10.00,
"feeAmount": null,
"feeCurrency": null,
"debitAmount": 10.00,
"creditAmount": 11.47,
"exchangeDate": "2021-03-01",
"expiryDateTime": "2021-03-01T10:00:00.00000",
"cutOffDateTime": "2021-03-01T10:00:00",
"settlementDate": "2021-03-01"
}
},
"connect": {},
"metadata": {}
}
Create An Exchange
POST /exchange-transactions
{
"workflow": {
"code": "client.direct.spot"
},
"data": {
"exchange": {
"quoteId": "00000000-0000-0000-0000-000000000000"
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210301-ABC123",
"fixedSide": "sell",
"rate": 1.146850353,
"serviceProviderRate": 1.158434700,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAmount": 11.47,
"serviceProviderBuyAmount": 11.58,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 10.00,
"serviceProviderSellAmount": 10.00,
"feeAmount": null,
"feeCurrency": null,
"debitAmount": 10.00,
"creditAmount": 11.47,
"rollCount": 0,
"originalExchangeDate": "2021-03-01",
"exchangeDate": "2021-03-01",
"cutOffDateTime": "2021-03-01T15:00:00",
"settlementDate": "2021-03-01",
"status": "pending",
"cancellationFee": null
}
},
"connect": {},
"metadata": {}
}
Get An Exchange
GET /exchange-transactions/{exchangeId}
{
"workflow": {},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210301-ABC123",
"fixedSide": "sell",
"rate": 1.146850353,
"serviceProviderRate": 1.158434700,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAmount": 11.47,
"serviceProviderBuyAmount": 11.58,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 10.00,
"serviceProviderSellAmount": 10.00,
"feeAmount": null,
"feeCurrency": null,
"debitAmount": 10.00,
"creditAmount": 11.47,
"rollCount": 0,
"originalExchangeDate": "2021-03-01",
"exchangeDate": "2021-03-01",
"cutOffDateTime": "2021-03-01T15:00:00",
"settlementDate": "2021-03-01",
"status": "pending",
"cancellationFee": null
}
},
"connect": {},
"metadata": {}
}
List Exchanges
GET /exchange-transactions
Supported query parameters:
| parameter | description |
|---|---|
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=10 |
| data.exchange.clientId | UUID of client |
| data.exchange.transactionNumber | unique transaction number |
| data.exchange.exchangeDateFrom | minimum exchange date |
| data.exchange.exchangeDateTo | maximum exchange date |
| data.exchange.sellCurrency | ISO 4217 currency code |
| data.exchange.buyCurrency | ISO 4217 currency code |
| data.exchange.sellAmountFrom | minimum sell amount |
| data.exchange.sellAmountTo | maximum sell amount |
| data.exchange.buyAmountFrom | minimum buy amount |
| data.exchange.buyAmountTo | maximum buy amount |
| data.exchange.serviceProvider | |
| data.exchange.serviceProviderId | |
| data.exchange.serviceProviderReference |
{
"workflow": {},
"data": {
"exchanges": [{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210301-ABC123",
"fixedSide": "sell",
"rate": 1.146850353,
"serviceProviderRate": 1.158434700,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAmount": 11.47,
"serviceProviderBuyAmount": 11.58,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 10.00,
"serviceProviderSellAmount": 10.00,
"feeAmount": null,
"feeCurrency": null,
"debitAmount": 10.00,
"creditAmount": 11.47,
"rollCount": 0,
"originalExchangeDate": "2021-03-01",
"exchangeDate": "2021-03-01",
"cutOffDateTime": "2021-03-01T15:00:00",
"settlementDate": "2021-03-01",
"status": "pending",
"cancellationFee": null
}],
},
"connect": {},
"metadata": {
"page": {
"size": 10,
"number": 0,
"totalElements": 1,
"totalPages": 1
}
}
}
Update Exchange
Exchanges can be updated as cancelled.
PATCH /exchange-transactions/{exchangeId}
{
"workflow": {
"code": "client.direct.spot"
},
"data": {
"exchange": {
"status": "cancelled",
"cancellationFee": 1500
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210301-ABC123",
"fixedSide": "sell",
"rate": 1.146850353,
"serviceProviderRate": 1.158434700,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAmount": 11.47,
"serviceProviderBuyAmount": 11.58,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 10.00,
"serviceProviderSellAmount": 10.00,
"feeAmount": null,
"feeCurrency": null,
"debitAmount": 10.00,
"creditAmount": 11.47,
"rollCount": 0,
"originalExchangeDate": "2021-03-01",
"exchangeDate": "2021-03-01",
"cutOffDateTime": "2021-03-01T15:00:00",
"settlementDate": "2021-03-01",
"status": "cancelled",
"cancellationFee": 150
}
},
"connect": {},
"metadata": {}
}
Webhooks
Exchange webhooks have "exchanges" as the module in the webhook container object.
There are three types of webhooks sent for exchanges:
- exchange-completed
- exchange-failed
- exchange-cancelled
These types are exposed in the webhook.type field.
{
"webhook": {
"module": "exchanges",
"type": "exchange-completed"
},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20210301-ABC123",
"fixedSide": "sell",
"rate": 1.146850353,
"serviceProviderRate": 1.158434700,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAmount": 11.47,
"serviceProviderBuyAmount": 11.58,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 10.00,
"serviceProviderSellAmount": 10.00,
"feeAmount": null,
"feeCurrency": null,
"debitAmount": 10.00,
"creditAmount": 11.47,
"rollCount": 0,
"originalExchangeDate": "2021-03-01",
"exchangeDate": "2021-03-01",
"cutOffDateTime": "2021-03-01T15:00:00",
"settlementDate": "2021-03-01",
"status": "pending",
"cancellationFee": null
}
},
"connect": {},
"metadata": {}
}
Updated 10 months ago