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 exchange rate 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 allocated time expires, the client or organization must then re-quote to get a new valid rate. Our system calculates the value date and the settlement date of the exchange according to each currency's cut-off times and holidays. 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, doing this also increments the roll count. A User can see that number if they call the 'Get Exchange Request' and check the 'rollCount' parameter.
The owner of an Exchange Transaction can be one of the following:
1. Client : When creating an Exchange Transaction, if the workflow code is client direct, the owner of this transaction is the client.
2. Organization : When creating an Exchange Transaction, if the workflow code is organization direct, the owner of this transaction is the organization.
Actual & Virtual Transaction Relation
Client transactions created on accounts from service providers with Virtual Account, Virtualized Real Account or Shared Pool Account models need to be also created on the Client Money Account. While processing the transaction, a copy of it is created on the Client Money Account which debits the balance it. These 2 transactions are created on the service provider only once, so they have a single representation on the service provider side.
These 2 transactions are linked to each other over related transaction field on the transaction data:
...
"relatedTransaction": {
"nature": "actual/virtual",
"id": "00000000-0000-0000-0000-000000000000"
},
...
relatedTransaction is optional, so nature is only present if the underlying account model requires it and id is only present when both transactions are created successfully.
Please refer to Flow of Funds section for more details on this subject:
Quote a rate
The process of creating an Exchange Quote is executed using two different workflows. These workflows can be as follows:
- Client Direct: To create an Exchange Quote whose owner is the Client, the workflow code must be
client.direct. In this casesellAccountIdandbuyAccountIdcorresponds to an ID of a client account. To be able to retrieve a quote, the client must have an active account for both currencies. - Organization Direct: To create an Exchange Quote whose owner is Organization, the workflow code must be
organization.direct. TheclientIdfield must be empty when the workflow code is organization. In this casesellAccountIdandbuyAccountIdcorresponds to an ID of a transaction account. To be able to retrieve a quote, the organization must have an active transaction 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": {
},
"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": {
},
"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": "organization.direct.spot",
"pricing": {
"enabled": null,
"sourcingMethod": "implicit"
}
},
"data": {
"quote": {
"clientId": null,
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 30
}
},
"connect": {
},
"metadata": {}
}
{
"workflow": {
"code": "organization.direct.spot",
"pricing": {
"enabled": true,
"sourcingMethod": "explicit",
"chargingType": "markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"clientId": null,
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 130.00
},
"pricing": {
"type": "ratio",
"ratio": "0.005"
}
},
"connect": {
},
"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": {
"serviceProvider": "currencycloud"
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "implicit"
}
},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 1.128409920,
"buyCurrency": "EUR",
"buyAmount": 39.49,
"sellCurrency": "GBP",
"sellAmount": 35.00,
"feeAmount": 0.00,
"feeCurrency": "EUR",
"exchangeDate": "2024-09-04",
"expiryDateTime": "2024-09-04T13:17:46.859882305",
"cutOffDateTime": "2024-09-04T22:59:00",
"settlementDate": "2024-09-04",
"offline": false,
"debitAmount": 35.00,
"creditAmount": 39.49
}
},
"connect": {
"serviceProvider": "nium"
},
"metadata": {}
}
{
"workflow": {
"code": "organization.direct.spot",
"pricing": {
"sourcingMethod": "implicit"
}
},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 1.181754,
"buyCurrency": "EUR",
"buyAmount": 35.45,
"sellCurrency": "GBP",
"sellAmount": 30.00,
"feeAmount": 0,
"feeCurrency": null,
"exchangeDate": "2024-09-03",
"expiryDateTime": "2024-09-02T20:00:53.377574011",
"cutOffDateTime": "2024-09-03T12:50:00",
"settlementDate": "2024-09-03",
"offline": false,
"debitAmount": 30.00,
"creditAmount": 35.45
}
},
"connect": {
"serviceProvider": "currencycloud"
},
"metadata": {}
}
{
"workflow": {
"code": "organization.direct.spot",
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 1.181614,
"buyCurrency": "EUR",
"buyAmount": 153.61,
"sellCurrency": "GBP",
"sellAmount": 130.00,
"feeAmount": 0,
"feeCurrency": null,
"exchangeDate": "2024-09-09",
"expiryDateTime": "2024-09-09T08:33:03.728836236",
"cutOffDateTime": "2024-09-09T12:50:00",
"settlementDate": "2024-09-09",
"offline": false,
"debitAmount": 130.00,
"creditAmount": 153.61
}
},
"connect": {
"serviceProvider": "currencycloud"
},
"metadata": {}
}
Requote
If the client or organization 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 or the organization will need the transaction 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": {
},
"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": {
},
"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": {
},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"enabled": null,
"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": 35
}
},
"connect": {
},
"metadata": {}
}
{
"workflow": {
"code": "organization.direct.spot",
"pricing": {
"enabled": null,
"sourcingMethod": "implicit"
}
},
"data": {
"quote": {
"clientId": null,
"fixedSide": "sell",
"sellCurrency": "GBP",
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"amount": 30
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "explicit",
"enabled": true,
"chargingType": "markup",
"chargingMethod": "on-source"
}
},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 0.823696223,
"buyCurrency": "GBP",
"buyAmount": 0.82,
"sellCurrency": "EUR",
"sellAmount": 1.00,
"feeAmount": 0,
"feeCurrency": null,
"exchangeDate": "2024-09-08",
"expiryDateTime": "2024-09-08T16:51:57.369575613",
"cutOffDateTime": "2024-09-08T23:55:00",
"settlementDate": "2024-09-08",
"offline": true,
"debitAmount": 1.00,
"creditAmount": 0.82
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot",
"pricing": {
"sourcingMethod": "implicit"
}
},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 1.128409920,
"buyCurrency": "EUR",
"buyAmount": 45.14,
"sellCurrency": "GBP",
"sellAmount": 40.00,
"feeAmount": 0.00,
"feeCurrency": "EUR",
"exchangeDate": "2024-09-04",
"expiryDateTime": "2024-09-04T13:26:49.525326825",
"cutOffDateTime": "2024-09-04T22:59:00",
"settlementDate": "2024-09-04",
"offline": false,
"debitAmount": 40.00,
"creditAmount": 45.14
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "organization.direct.spot",
"pricing": {
"sourcingMethod": "implicit"
}
},
"data": {
"quote": {
"id": "00000000-0000-0000-0000-000000000000",
"rate": 1.181754,
"buyCurrency": "EUR",
"buyAmount": 35.45,
"sellCurrency": "GBP",
"sellAmount": 30.00,
"feeAmount": 0,
"feeCurrency": null,
"exchangeDate": "2024-09-03",
"expiryDateTime": "2024-09-02T20:07:37.650973633",
"cutOffDateTime": "2024-09-03T12:50:00",
"settlementDate": "2024-09-03",
"offline": false,
"debitAmount": 30.00,
"creditAmount": 35.45
}
},
"connect": {},
"metadata": {}
}
Create An Exchange
The process of creating an Exchange Transaction is executed using two different workflows. These workflows can be as follows:
- Client Direct: To create an Exchange Transaction whose owner is the Client, the workflow code must be
client.direct. In this casesellAccountIdandbuyAccountIdcorresponds to an ID of a client account. To be able to create an Exchange Transaction, the client must have an active account for both currencies. - Organization Direct: To create an Exchange Transaction whose owner is Organization, the workflow code must be
organization.direct. TheclientIdfield must be empty when the workflow code is organization. In this casesellAccountIdandbuyAccountIdcorresponds to an ID of a transaction account. To be able to create an Exchange Transaction, the organization must have an active transaction account for both currencies.
POST /exchange-transactions
{
"workflow": {
"code": "client.direct.spot"
},
"data": {
"exchange": {
"quoteId": "00000000-0000-0000-0000-000000000000"
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "organization.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,
"owner": "client",
"relatedTransaction": {
"nature": null,
"id": null
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "organization.direct.spot"
},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20240904-3QE6N4",
"fixedSide": "sell",
"rate": 1.181754000,
"serviceProviderRate": 1.181754000,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAmount": 35.45,
"serviceProviderBuyAmount": 35.45,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 30.00,
"serviceProviderSellAmount": 30.00,
"feeAmount": 0.00,
"feeCurrency": null,
"debitAmount": 30.00,
"creditAmount": 35.45,
"rollCount": 0,
"originalExchangeDate": "2024-09-05",
"exchangeDate": "2024-09-05",
"cutOffDateTime": "2024-09-05T12:50:00",
"settlementDate": "2024-09-05",
"status": "pending",
"cancellationFee": null,
"owner": "organization",
"relatedTransaction": {
"nature": null,
"id": 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,
"owner": "client",
"relatedTransaction": {
"nature": null,
"id": null
}
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20240904-3QE6N4",
"fixedSide": "sell",
"rate": 1.181754000,
"serviceProviderRate": 1.181754000,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "EUR",
"buyAmount": 35.45,
"serviceProviderBuyAmount": 35.45,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 30.00,
"serviceProviderSellAmount": 30.00,
"feeAmount": 0.00,
"feeCurrency": null,
"debitAmount": 30.00,
"creditAmount": 35.45,
"rollCount": 0,
"originalExchangeDate": "2024-09-05",
"exchangeDate": "2024-09-05",
"cutOffDateTime": "2024-09-05T12:50:00",
"settlementDate": "2024-09-05",
"status": "completed",
"cancellationFee": null,
"owner": "organization",
"relatedTransaction": {
"nature": null,
"id": 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 | |
| data.exchange.owner | "client" or "organization" |
| data.exchange.hasRelatedTransaction | used to filter if the transfer has any related transaction. one of true , false |
| data.exchange.relatedTransactionId | UUID of related transaction |
| data.exchange.relatedTransactionNature | Nature of the related transaction. one of virtual, actual |
{
"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,
"owner": "organization",
"relatedTransaction": {
"nature": null,
"id": null
}
}],
},
"connect": {},
"metadata": {
"page": {
"size": 10,
"number": 0,
"totalElements": 1,
"totalPages": 1
}
}
}
data.exchange.owner has a default value of client to be backward compatible. The default value will be removed in the future. Please send client explicitly if you'd like to list only the client transactions
Update Exchange
Exchanges can be updated as canceled.
PATCH /exchange-transactions/{exchangeId}
{
"workflow": {
"code": "client.direct.spot"
},
"data": {
"exchange": {
"status": "cancelled",
"cancellationFee": 0
}
},
"connect": {},
"metadata": {}
}
{
"workflow": {
"code": "client.direct.spot"
},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20240909-AD957K",
"fixedSide": "sell",
"rate": 1.266800000,
"serviceProviderRate": 1.266800000,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "USD",
"buyAmount": 44.34,
"serviceProviderBuyAmount": 44.34,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 35.00,
"serviceProviderSellAmount": 35.00,
"feeAmount": 2.22,
"feeCurrency": "USD",
"debitAmount": 35.00,
"creditAmount": 42.12,
"rollCount": 0,
"originalExchangeDate": "2024-09-09",
"exchangeDate": "2024-09-09",
"cutOffDateTime": "2024-09-09T14:30:00",
"settlementDate": "2024-09-09",
"status": "cancelled",
"cancellationFee": 0,
"owner": "client",
"relatedTransaction": {
"nature": null,
"id": null
}
}
},
"connect": {},
"metadata": {}
}
Webhooks
Exchange 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": "completed",
"cancellationFee": null,
"owner": "client",
"relatedTransaction": {
"nature": null,
"id": null
}
}
},
"connect": {},
"metadata": {}
}
{
"webhook": {
"module": "exchanges",
"type": "exchange-cancelled"
},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20240909-EL837Y",
"fixedSide": "sell",
"rate": 1.266800000,
"serviceProviderRate": 1.266800000,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "USD",
"buyAmount": 44.34,
"serviceProviderBuyAmount": 44.34,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 35.00,
"serviceProviderSellAmount": 35.00,
"feeAmount": 2.22,
"feeCurrency": "USD",
"debitAmount": 35.00,
"creditAmount": 42.12,
"rollCount": 0,
"originalExchangeDate": "2021-03-01",
"exchangeDate": "2021-03-01",
"cutOffDateTime": "2021-03-01T15:00:00",
"settlementDate": "2021-03-01",
"status": "cancelled",
"cancellationFee": 0,
"owner": "client",
"relatedTransaction": {
"nature": null,
"id": null
}
}
},
"connect": {},
"metadata": {}
}
Exchange Connection Webhooks: Exchange connection webhooks have "exchanges" in the module field in the webhook container object. Also, there is a "connection" object in the exchange object.
There are 6 types of webhooks sent for exchanges:
- connection-creation-instructed
- connection-created
- connection-creation-failed
- connection-update-instructed
- connection-updated
- connection-update-failed
These types are exposed in the webhook.type field.
{
"webhook": {
"module": "exchange-transactions",
"type": "connection-creation-instructed"
},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20241211-QMXWJJ",
"fixedSide": "sell",
"rate": 1.266800000,
"serviceProviderRate": 1.266800000,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "USD",
"buyAmount": 44.34,
"serviceProviderBuyAmount": 44.34,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 35.00,
"serviceProviderSellAmount": 35.00,
"feeAmount": 2.11,
"feeCurrency": "USD",
"debitAmount": 35.00,
"creditAmount": 42.23,
"rollCount": 0,
"originalExchangeDate": "2024-12-11",
"exchangeDate": "2024-12-11",
"cutOffDateTime": "2024-12-11T15:30:00",
"settlementDate": "2024-12-11",
"status": "pending",
"cancellationFee": null,
"owner": "client",
"relatedTransaction": {
"nature": null,
"id": null
},
"connection": {
"serviceProvider": "currencycloud",
"state": "creation-in-progress",
"method": "built-in"
}
}
},
"connect": {
"connection": {
"serviceProvider": "currencycloud",
"state": "creation-in-progress",
"method": "built-in"
}
},
"metadata": {}
}
{
"webhook": {
"module": "exchange-transactions",
"type": "connection-created"
},
"data": {
"exchange": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"quoteId": "00000000-0000-0000-0000-000000000000",
"transactionNumber": "20241211-QMXWJJ",
"fixedSide": "sell",
"rate": 1.266800000,
"serviceProviderRate": 1.266800000,
"buyAccountId": "00000000-0000-0000-0000-000000000000",
"buyCurrency": "USD",
"buyAmount": 44.34,
"serviceProviderBuyAmount": 44.34,
"sellAccountId": "00000000-0000-0000-0000-000000000000",
"sellCurrency": "GBP",
"sellAmount": 35.00,
"serviceProviderSellAmount": 35.00,
"feeAmount": 2.11,
"feeCurrency": "USD",
"debitAmount": 35.00,
"creditAmount": 42.23,
"rollCount": 0,
"originalExchangeDate": "2024-12-11",
"exchangeDate": "2024-12-11",
"cutOffDateTime": "2024-12-11T15:30:00",
"settlementDate": "2024-12-11",
"status": "pending",
"cancellationFee": null,
"owner": "client",
"relatedTransaction": {
"nature": null,
"id": null
},
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "currencycloud",
"reference": "20241211-MPBTND",
"state": "completed-up-to-date",
"status": "pending",
"method": "built-in"
}
}
},
"connect": {
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "currencycloud",
"reference": "20241211-MPBTND",
"state": "completed-up-to-date",
"status": "pending",
"method": "built-in"
}
},
"metadata": {}
}
Updated 9 days ago