FX Rates

You can access information about currency exchange rates used for customer transactions. This is helpful when a customer wants to pay in a different currency than you receive. We handle the currency exchange for the customer. You can obtain a list of currency pairs for which exchange rates are available. You can retrieve exchange rates for one or multiple currency pairs from this list.

Currency pairs (base currency and quote currency) can include any combination of fiat and cryptocurrency. The rate indicates how much quote currency is needed for one unit of base currency. The buy rate applies when the API provider purchases the base currency (a customer exchanges their base currency for the quote currency). The sell rate applies when the API provider sells the base currency (a customer exchanges their quote currency for the base currency)..

Authorization token

As described in the General concepts - Security section, you should generate authorization token first. You should use your merchant ID and your secret.

Example CURL for requesting available payment options
curl --location 'https://api.sandbox.carpentum.tech/auth-tokens' \
--header 'X-API-Version: 2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "merchantCode": "CAR21-RAAFG0CDWO",
    "secret": "v4sCfq8SqOefqdUwGwe0WzQgya1o7atUeuvwoh4KcnUH4KBFfZ",
    "validitySecs": 3600,
    "operations": [
        "GET /fx-rate-pairs",
        "GET /fx-rates"
    ]
}'
Response of the example call
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIkdFVCAvZngtcmF0ZS1wYWlycyIsIkdFVCAvZngtcmF0ZXMiXSwidGVuYW50Q29kZSI6IkNBUiIsImlkQ3VzdG9tZXIiOiJkaXNwb3NhYmxlLTQ2N2EyMWJhLWRjYTctNGIxNy05MWVmLTkzOGFiZTliNDI2NiIsInNldHRsZW1lbnRNZXRob2QiOm51bGwsImV4cCI6MTcyNTUyNTkyOCwianRpIjoiYmQxMTg1NWQtY2VlZC00NTkyLTg2MTYtMjc5OGZlZTc3MGY4IiwiaWF0IjoxNzI1NTI1MzI4LCJzdWIiOiJDQVIyMS1SQUFGRzBDRFdPIn0.b42qGXMtfJqYdsgVmAu60HxAWiieQHDM8C0mkeFnWNg"
}

Currency Pairs

Example CURL for requesting supported currency pairs
curl --location 'https://api.sandbox.carpentum.tech/fx-rate-pairs' \
--header 'X-API-Version: 2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIkdFVCAvZngtcmF0ZS1wYWlycyIsIkdFVCAvZngtcmF0ZXMiXSwidGVuYW50Q29kZSI6IkNBUiIsImlkQ3VzdG9tZXIiOiJkaXNwb3NhYmxlLTRiMzcwZjMxLWU3NzAtNDUwNS05YTQxLTdiNjA4OTE1MzJmZiIsInNldHRsZW1lbnRNZXRob2QiOm51bGwsImV4cCI6MTcyNTQ2ODUyMSwianRpIjoiZDFjNDczZTItZmRkNi00Y2M0LWJkM2ItNzM3N2VhYmIxNmNmIiwiaWF0IjoxNzI1NDY0OTIxLCJzdWIiOiJDQVIyMS1SQUFGRzBDRFdPIn0.-Q7ffTs5OtdxLGp0WfY13cz1Q274esfNdTrXrfddx5Y'
Response of the example call
{
  "data": [
    {
      "baseCurrencyCode": "USDT",
      "quoteCurrencyCode": "MYR"
    },
    {
      "baseCurrencyCode": "USDT",
      "quoteCurrencyCode": "INR"
    }
  ]
}

Getting all FX rates

Example CURL for requesting a list of all currently valid FX rates
curl --location 'https://api.sandbox.carpentum.tech/fx-rates' \
--header 'X-API-Version: 2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIkdFVCAvZngtcmF0ZS1wYWlycyIsIkdFVCAvZngtcmF0ZXMiXSwidGVuYW50Q29kZSI6IkNBUiIsImlkQ3VzdG9tZXIiOiJkaXNwb3NhYmxlLTRiMzcwZjMxLWU3NzAtNDUwNS05YTQxLTdiNjA4OTE1MzJmZiIsInNldHRsZW1lbnRNZXRob2QiOm51bGwsImV4cCI6MTcyNTQ2ODUyMSwianRpIjoiZDFjNDczZTItZmRkNi00Y2M0LWJkM2ItNzM3N2VhYmIxNmNmIiwiaWF0IjoxNzI1NDY0OTIxLCJzdWIiOiJDQVIyMS1SQUFGRzBDRFdPIn0.-Q7ffTs5OtdxLGp0WfY13cz1Q274esfNdTrXrfddx5Y'
Response of the example call
{
  "data": [
    {
      "baseCurrencyCode": "USDT",
      "quoteCurrencyCode": "MYR",
      "buyRate": 3.96,
      "sellRate": 5.05,
      "validUpTo": "3000-01-01T00:00:00Z"
    },
    {
      "baseCurrencyCode": "USDT",
      "quoteCurrencyCode": "INR",
      "buyRate": 82.17,
      "sellRate": 84.84,
      "validUpTo": "3000-01-01T00:00:00Z"
    }
  ]
}

Getting FX rates for a specific currency pair

Example CURL for requesting a list of all currently valid FX rates
curl --location 'https://api.sandbox.carpentum.tech/fx-rates?baseCurrencyCode=USDT&quoteCurrencyCode=INR' \
--header 'X-API-Version: 2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIkdFVCAvZngtcmF0ZS1wYWlycyIsIkdFVCAvZngtcmF0ZXMiXSwidGVuYW50Q29kZSI6IkNBUiIsImlkQ3VzdG9tZXIiOiJkaXNwb3NhYmxlLTgyY2EyODc3LTFiYmYtNDI3MS1hMGUyLWU4ZmZhODg4MjRiZCIsInNldHRsZW1lbnRNZXRob2QiOm51bGwsImV4cCI6MTcyNTUyNTMxMCwianRpIjoiODE1ZjU1M2YtYzcyNS00NWRjLTgxODEtOWEyNjM2OWQ4ZGY1IiwiaWF0IjoxNzI1NTIxNzEwLCJzdWIiOiJDQVIyMS1SQUFGRzBDRFdPIn0.MBxCk3d5lexbY6pxR9zU1bOYBz-xUzHkod_u3ULpzOY'
Response of the example call
{
  "data": [
    {
      "baseCurrencyCode": "USDT",
      "quoteCurrencyCode": "INR",
      "buyRate": 82.17,
      "sellRate": 84.84,
      "validUpTo": "3000-01-01T00:00:00Z"
    }
  ]
}