API reference

Currency exchange

Use the currency exchange endpoints to convert money between wallets that hold different currencies. GetExchangeRate returns the real-time exchange rate between two currencies. BookExchange debits a wallet in one currency, converts the amount at the real-time rate, and credits the result to a wallet in another currency.

Currencies are identified by three-letter ISO 4217 codes such as USD, EUR or AUD. Rates are real-time, so the rate can change slightly between a GetExchangeRate call and the BookExchange call that follows it. Both wallets in an exchange must belong to the account that makes it.

#Get an exchange rate

POST/API/v4/Payment/GetExchangeRate

Returns the real-time exchange rate for converting FromCurrency into ToCurrency. Call it before BookExchange to check the current rate.

The rate is returned in ExchangeRate inside ExchangeRateMethodsDetail. It's the number of units of ToCurrency that 1 unit of FromCurrency buys, so multiply an amount in FromCurrency by the rate to get its value in ToCurrency.

Note

The rate is real-time and can change slightly between a call to GetExchangeRate and a call to BookExchange.

Body parameters

  • GetExchangeRateobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • RequestobjectRequired

      Wrapper object for the request fields.

      Child parameters3
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • FromCurrencystringRequired

        Three-letter ISO 4217 code of the source currency you convert from, for example USD.

      • ToCurrencystringRequired

        Three-letter ISO 4217 code of the target currency you convert to, for example EUR.

Response fields

  • GetExchangeRateMethodsResponseobject

    Wrapper object for the response.

    Child parameters1
    • ExchangeRateMethodResultobject

      Result of the operation.

      Child parameters2
      • ExchangeRateMethodsobject

        Container for the exchange rate details.

        Child parameters1
        • ExchangeRateMethodsDetailobject[]

          List of exchange rate details, with one entry for the requested currency pair.

          Child parameters5
          • IssuerAccountNumberstring

            The Xtrm account identifier of the account that initiated the API call.

          • FromCurrencystring

            Three-letter ISO 4217 code of the source currency.

          • ToCurrencystring

            Three-letter ISO 4217 code of the target currency.

          • Amountnumber

            The amount of FromCurrency the rate is quoted for: always 1.

          • ExchangeRatenumber

            The real-time exchange rate: the number of units of ToCurrency that 1 unit of FromCurrency buys. Multiply an amount in FromCurrency by the rate to get its value in ToCurrency. For example, a USD to AUD rate of 1.4005406 means 1 USD converts to 1.4005406 AUD, so 100 USD converts to 140.05 AUD.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          The error messages when the call fails, as an array of strings. null on success, so decide with Success and use Errors only to explain a failure.

Related: Exchange currency between wallets

#Exchange currency between wallets

POST/API/v4/Payment/BookExchange

Converts money from one currency to another. Xtrm debits Amount, in FromCurrency, from the source wallet (FromWalletID), converts it at the real-time rate, and credits the result in ToCurrency to the destination wallet (ToWalletID). If you omit ToWalletID, Xtrm credits one of the account's wallets in the target currency, or creates one if there's none.

AccountNumber identifies the account that makes the exchange. It can be a company account (SPN) or a personal account (PAT). If it isn't your own account, your company must be connected to it. Without a connection, the call returns HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.

To check the current rate first, call GetExchangeRate. Xtrm doesn't hold that rate: BookExchange converts at the rate at the moment you book, which can differ slightly.

The response returns two transaction IDs: DebitTransactionID for the debit from the source wallet and CreditTransactionID for the credit to the destination wallet. Xtrm posts both before it responds, so the converted funds can pay a batch right away. Both appear in the wallets' transactions as Currency Exchange.

If the wallet in FromWalletID holds less than Amount, Xtrm rejects the exchange with HTTP 400 before it books anything, so no money is exchanged and nothing leaves the wallet. OperationStatus.Success is false, and Errors contains <FromWalletID> - Insufficient balance in the wallet.

Tip

The wallet transaction list endpoints (GetCompanyWalletTransactions and GetUserWalletTransactions) accept Currency Exchange as a TransactionType filter value.

Body parameters

  • BookExchangeobjectRequired

    Wrapper object for the operation.

    Child parameters1
    • RequestobjectRequired

      Wrapper object for the request fields.

      Child parameters7
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • AccountNumberstringRequired

        The Xtrm account number of the account that makes the exchange, starting with SPN for company accounts or PAT for personal accounts. Both wallets in the exchange must belong to this account.

      • FromWalletIDstringRequired

        The numeric WalletID of the source wallet that the funds are debited from, for example "122181". It must be a wallet of the account in AccountNumber, in FromCurrency. Wallet names aren't accepted.

      • FromCurrencystringRequired

        Three-letter ISO 4217 code of the currency you sell, for example USD.

      • ToCurrencystringRequired

        Three-letter ISO 4217 code of the currency you buy, for example EUR.

      • AmountstringRequired

        Amount to exchange as a decimal string, for example "365.00". Denominated in FromCurrency. The wallet in FromWalletID must hold at least this amount; an Amount equal to its balance is accepted.

      • ToWalletIDstringOptional

        The numeric WalletID of the destination wallet that receives the converted money, for example "122182". It must be a wallet of the account in AccountNumber, in ToCurrency. If you omit it, Xtrm credits one of the account's wallets in ToCurrency, or creates one if there's none. A value that isn't a number, such as the wallet's name, counts as omitted, so always send the numeric ID.

Response fields

  • BookExchangeMethodsResponseobject

    Wrapper object for the response.

    Child parameters1
    • BookExchangeMethodResultobject

      Result of the operation.

      Child parameters2
      • BookExchangeMethodsobject

        Container for the exchange details.

        Child parameters1
        • BookExchangeMethodsDetailobject

          Details of the booked exchange.

          Child parameters4
          • DebitTransactionIDinteger

            Unique identifier of the debit transaction from the source wallet.

          • CreditTransactionIDinteger

            Unique identifier of the credit transaction into the destination wallet.

          • PaymentDatestring

            Timestamp of when the exchange was processed, for example "2026-06-04T00:00:00-04:00".

          • PaymentStatusstring

            Status of the exchange: always Completed on success.

      • OperationStatusobject

        Outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          The error messages when the call fails, as an array of strings. null on success, so decide with Success and use Errors only to explain a failure.

#Errors

MessageMeaning
400 · Insufficient balance in the walletThe wallet in FromWalletID holds less than Amount. Errors contains <FromWalletID> - Insufficient balance in the wallet. Xtrm books nothing and doesn't debit the wallet. Fund the wallet or exchange a smaller amount, then book again.
400 · Not authorized to access this resource. Make One Time Password API Call to access this resourceThe account in AccountNumber isn't your company's own account and isn't connected to it. A Pending connection doesn't count. Connect the account first, for example with a one-time password, then book again. See Connections and manager services.

Related: Get an exchange rate · List company wallets · List an individual recipient's wallets · Create a company wallet · Create an individual recipient's wallet · List company wallet transactions · List an individual recipient's wallet transactions