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:

parameterdescription
metadata.page.number0-indexed, default=0
metadata.page.sizedefault=10
data.exchange.clientIdUUID of client
data.exchange.transactionNumberunique transaction number
data.exchange.exchangeDateFromminimum exchange date
data.exchange.exchangeDateTomaximum exchange date
data.exchange.sellCurrencyISO 4217 currency code
data.exchange.buyCurrencyISO 4217 currency code
data.exchange.sellAmountFromminimum sell amount
data.exchange.sellAmountTomaximum sell amount
data.exchange.buyAmountFromminimum buy amount
data.exchange.buyAmountTomaximum 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": {}
}