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",
            "quoteId": "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

definition

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": {}
}