Guide

Exchange currency

To make a batch payment in another currency, exchange funds into a company wallet in that currency, then pay the batch from that wallet. Currency exchange (FX: converting money from one currency into another) is part of managing your wallets: you check the rate with GetExchangeRate and book the exchange with BookExchange. Payments and currency exchange are executed by regulated financial partners.

Every item in a batch is paid in one currency: the currency of the batch's source wallet (SourceWalletId). A bank item can still go to a bank account in another currency: the amount is converted when it's transferred to the bank. To pay wallets, gift cards or prepaid cards in another currency, though, you exchange the funds into a wallet in that currency first, then pay the batch from that wallet. Checks and Rapid Transfer items pay only from a USD batch. See Currency for the full rules.

In this guide you prepare a batch that pays Jane Doe (PAT9999888) AUD 500.00, from US dollars your company holds in its wallet 122181. You list your wallets, create an AUD wallet, check the real-time exchange rate, exchange enough US dollars to cover the batch, confirm the AUD balance, and submit the batch with that wallet as its source.

#Before you begin

  • Sandbox credentials. In your sandbox company account, go to Settings > Integrations > Get Credentials for your client ID and secret. See Sandbox & environments.
  • An access token in the XTRM_ACCESS_TOKEN environment variable. See Authentication.
  • Your company's account number (SPN), which you send as IssuerAccountNumber. The samples use SPN1111222.
  • A funded wallet in the currency you convert from. In the sandbox, Xtrm credits test funds to your wallets after approving your IP addresses; see Test funds. To add more, see Fund your wallet.
  • The batch payment you're preparing: its currency and the total of its items' Amount values. Currencies are three-letter ISO 4217 codes, such as USD and AUD. Create a batch payment shows how to build the items.

Each sample below runs on its own, so values from one step's response (such as wallet IDs) are typed in literally in the next. Replace them with the values your own responses return.

#Exchange funds into the batch's source wallet

  1. Find your wallets

    Call GetCompanyWallets to list your company's wallets. You're looking for two of them:

    • The wallet you convert from, here in USD, with a WalletBalance that covers the amount you plan to exchange.
    • The wallet in the batch's currency, here AUD. It's the wallet you name as SourceWalletId, and the batch is paid from that wallet alone.

    Companies can hold more than one wallet per currency, so choose each wallet by its WalletID, not by its currency alone.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetCompanyWallets" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetCompanyWallets": {
        "request": {
          "IssuerAccountNumber": "SPN1111222"
        }
      }
    }'
    Response (excerpt)
    {
      "GetCompanyWalletResponse": {
        "CompanyWalletResult": {
          "CompanyWallets": {
            "CompanyWalletDetails": [
              {
                "WalletID": 122181,
                "WalletName": "USD Wallet for Main Company",
                "WalletCurrency": "USD",
                "WalletBalance": 57715.15,
                "WalletType": "Standard",
                "IsBankLinked": false,
                "AllowWalletLinkedBankOverride": false,
                "EntityID": 12345
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep for the next steps: the USD wallet's WalletID (122181) and its WalletBalance (57715.15), so you can compare the balance after the exchange. If you already have a wallet in the batch's currency, keep its WalletID and WalletBalance too. Responses return WalletID as a number. The exchange request sends wallet IDs as strings ("122181"), but SourceWalletId in the batch is an integer (122182). Every wallet field takes the numeric ID, never the wallet's name.

    This company has no AUD wallet yet, so the next step creates one. If you already have a wallet in the batch's currency, skip to step 3.

  2. Create a wallet in the batch's currency (if needed)

    Create the wallet your batch will pay from with CreateCompanyWallet, with WalletCurrency set to the batch's currency and WalletType set to Standard. A wallet's currency can't change after you create it. Fund your wallet explains every field of this call.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/CreateCompanyWallet" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "CreateCompanyWallet": {
        "request": {
          "IssuerAccountNumber": "SPN1111222",
          "WalletName": "Australian Dollars Wallet",
          "WalletCurrency": "AUD",
          "WalletType": "Standard"
        }
      }
    }'
    Response (excerpt)
    {
      "CreateCompanyWalletResponse": {
        "CreateCompanyWalletResult": {
          "WalletID": 122182,
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep for the next steps: the new AUD wallet's WalletID (122182). You book the exchange into it in step 4, and it's the SourceWalletId of your batch in step 6. A new wallet starts with a balance of 0, so after the exchange its WalletBalance is exactly what the exchange credited.

  3. Check the exchange rate

    Call GetExchangeRate with the currency you convert from (FromCurrency) and the batch's currency (ToCurrency). It returns the current real-time rate, quoted for 1 unit of FromCurrency (an Amount of 1). BookExchange takes its Amount in FromCurrency, while your batch total is in ToCurrency, so you use the rate to size the exchange, as shown below the response.

    The exchange endpoints wrap their fields in Request, and BatchTransfer has no wrapper. We recommend copying each body as shown (see Requests & responses).

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Payment/GetExchangeRate" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "GetExchangeRate": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "FromCurrency": "USD",
          "ToCurrency": "AUD"
        }
      }
    }'
    Response
    {
      "GetExchangeRateMethodsResponse": {
        "ExchangeRateMethodResult": {
          "ExchangeRateMethods": {
            "ExchangeRateMethodsDetail": [
              {
                "IssuerAccountNumber": "SPN1111222",
                "FromCurrency": "USD",
                "ToCurrency": "AUD",
                "Amount": 1,
                "ExchangeRate": 1.4005406
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep for your records: ExchangeRate, the real-time rate between the two currencies. 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. Here, USD 1.00 buys AUD 1.4005406, so USD 100.00 converts to AUD 140.05. To estimate how much to exchange, divide the amount you need in ToCurrency by the rate: at this rate, the batch's AUD 500.00 takes about USD 357.01. This guide exchanges USD 365.00, about AUD 511.20 at this rate, which leaves headroom for the item's fee and for the rate moving before you book. Check the amount credited in step 5 before you submit the batch. ExchangeRateMethodsDetail is an array with one entry, for the currency pair you asked for.

    The rate isn't part of the booking

    BookExchange has no field for a rate or a quote reference, so nothing from this response goes into the next request. Xtrm books the exchange at the real-time rate at the moment of booking, which can differ slightly from the rate this call returned.

  4. Book the exchange into the source wallet

    Call BookExchange. Xtrm debits Amount, in FromCurrency, from the wallet in FromWalletID, exchanges it at the real-time rate, and credits the result in ToCurrency to the wallet in ToWalletID.

    • IssuerAccountNumber is your company's SPN.
    • AccountNumber is the account that executes the exchange. Both wallets need to belong to it. You're exchanging between your own company's wallets, so it's the same SPN. Any other account must be connected to your company.
    • FromWalletID is the wallet you convert from (122181, step 1).
    • ToWalletID is your batch's source wallet (122182, step 2). It's optional: if you leave it out, Xtrm credits one of the account's wallets in ToCurrency, or creates one if there's none, and that isn't necessarily the wallet your batch pays from. We recommend always sending it, as the numeric ID: a value that isn't a number, such as the wallet's name, counts as left out.
    • Amount is a decimal string in FromCurrency: here, "365.00" US dollars, sized in step 3 to cover the AUD 500.00 batch. The wallet in FromWalletID must hold at least this amount, or Xtrm refuses the exchange (see When you exchange).
    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Payment/BookExchange" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "BookExchange": {
        "Request": {
          "IssuerAccountNumber": "SPN1111222",
          "AccountNumber": "SPN1111222",
          "FromWalletID": "122181",
          "FromCurrency": "USD",
          "ToCurrency": "AUD",
          "Amount": "365.00",
          "ToWalletID": "122182"
        }
      }
    }'
    Response
    {
      "BookExchangeMethodsResponse": {
        "BookExchangeMethodResult": {
          "BookExchangeMethods": {
            "BookExchangeMethodsDetail": {
              "DebitTransactionID": 888111,
              "CreditTransactionID": 888222,
              "PaymentDate": "2026-06-04T00:00:00-04:00",
              "PaymentStatus": "Completed"
            }
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Keep for your records: DebitTransactionID (the debit from the wallet you converted from) and CreditTransactionID (the credit to your batch's source wallet), with PaymentDate and PaymentStatus. We recommend storing both transaction IDs next to your own record of the batch they pay for. PaymentStatus is always Completed on success: Xtrm posts the debit and the credit before it responds, so the converted funds can pay a batch right away.

    The response doesn't include the rate that was applied or the amount credited. The next step shows what arrived.

  5. Confirm the source wallet's balance

    Call GetCompanyWallets again, with the same request as in step 1, and compare each wallet's WalletBalance with the values you kept. The wallet you converted from is debited, and your batch's source wallet is credited.

    Response (excerpt)
    {
      "GetCompanyWalletResponse": {
        "CompanyWalletResult": {
          "CompanyWallets": {
            "CompanyWalletDetails": [
              {
                "WalletID": 122181,
                "WalletName": "USD Wallet for Main Company",
                "WalletCurrency": "USD",
                "WalletBalance": 57350.15,
                "WalletType": "Standard",
                "IsBankLinked": false,
                "AllowWalletLinkedBankOverride": false,
                "EntityID": 12345
              },
              {
                "WalletID": 122182,
                "WalletName": "Australian Dollars Wallet",
                "WalletCurrency": "AUD",
                "WalletBalance": 511.13,
                "WalletType": "Standard",
                "IsBankLinked": false,
                "AllowWalletLinkedBankOverride": false,
                "EntityID": 12345
              }
            ]
          },
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    The USD wallet is down by the USD 365.00 you exchanged, and the new AUD wallet holds AUD 511.13. That's slightly less than the AUD 511.20 estimated in step 3, because the booking used the rate at that moment, so always take the amount received from the balance, not from the rate.

    Before you submit the batch, check that the source wallet's balance covers the total of your items' Amount values plus their fees. Here, AUD 511.13 covers the AUD 500.00 item and leaves AUD 11.13 for its fee. A 202 Accepted response to a batch says nothing about the balance: Xtrm debits each item when it processes it, for the item's Amount plus its fee, and an item the source wallet can't cover fails with INSUFFICIENT_BALANCE.

    The wallets also record the exchange as two Currency Exchange transactions, the debit and the credit. To list them, call GetCompanyWalletTransactions for the wallet, with Filters.TransactionType set to Currency Exchange. See Track & reconcile payments.

    Keep for the next step: the source wallet's WalletID (122182), which you send as SourceWalletId.

  6. Submit the batch payment from that wallet

    Submit your batch with BatchTransfer and name the wallet you just exchanged into as SourceWalletId. The batch takes its currency from that wallet, so every item's Amount is in Australian dollars.

    This example pays Jane Doe (PAT9999888) AUD 500.00 into her Xtrm wallet (XTR94502). Amount is a number. Its Destination is empty, so Xtrm credits her oldest active Standard wallet in AUD, or creates one named Wallet - AUD because she has no wallet in that currency yet. A wallet item with an empty Destination needs no connection to the recipient. For how Xtrm processes a batch, see How batch payments work. For every send method and option, see Create a batch payment.

    The batch uses this guide's own IDs, BATCH-FX-0001 and TXN-FX-0001. CustomerBatchId values are shared across all Xtrm accounts, so replace them with your own unique values before you run this in the sandbox, and give every new batch new IDs. See Batch and payment identifiers.

    curl -X POST "https://xapisandbox.xtrm.com/API/v4/Fund/BatchTransfer" \
      -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
      "IssuerAccountNumber": "SPN1111222",
      "SourceWalletId": 122182,
      "CustomerBatchId": "BATCH-FX-0001",
      "Items": [
        {
          "CustomerTransactionId": "TXN-FX-0001",
          "RecipientId": "PAT9999888",
          "Amount": 500,
          "SendMethodId": "XTR94502",
          "Destination": {}
        }
      ]
    }'

    Xtrm responds with 202 Accepted and pays the item in the background. Create a batch payment explains the whole response. In this one, check that:

    • ItemsCount.Accepted is 1 and the Rejected array is empty.
    • The entry in Accepted shows Amount 500 and Currency AUD, the currency of your source wallet.

    The item ends Success once Jane Doe's AUD wallet is credited. Follow it with the payment status endpoint, using BATCH-FX-0001 and TXN-FX-0001; it reports Currency AUD. See Batch and payment statuses. If the submit call times out, resend it unchanged, with the same IDs (see A safe retry pattern).

#What can go wrong

A wallet or exchange call in this guide that fails returns HTTP 400 with OperationStatus.Success set to false and the reasons in OperationStatus.Errors. Decide with Success: on success, Errors is null or [], depending on the endpoint. GetExchangeRate and BookExchange also return 503, with Currency exchange service temporarily unavailable. Please try again later., when Xtrm can't get a rate or complete the exchange. Before you resend a BookExchange, check the wallet you convert from (see below). For the other statuses, see HTTP status codes. For a batch item that's rejected or fails, see Errors and Error codes on attempts.

#When you exchange

  • The rate moved. The exchange happens at the real-time rate when you call BookExchange, which can differ slightly from what GetExchangeRate returned a moment earlier. If the source wallet ends up short of your batch total, exchange the difference before you submit.
  • The funds went to a different wallet. Without ToWalletID, or with a value that isn't a number such as a wallet name, Xtrm credits one of the account's wallets in ToCurrency, which isn't necessarily the wallet you name in SourceWalletId. Send ToWalletID set to your batch's source wallet.
  • A wallet belongs to another account. FromWalletID and ToWalletID both need to belong to the account in AccountNumber, in FromCurrency and ToCurrency. Otherwise Xtrm refuses the exchange with <FromWalletID> - Invalid from wallet id or <ToWalletID> - Invalid to wallet id. An exchange never moves money from one account to another.
  • The wallet you convert from is short. 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. An Amount equal to the wallet balance is accepted. Fund the wallet or exchange a smaller amount, then book again.
  • Wallet creation fails. CreateCompanyWallet refuses a WalletCurrency that Xtrm doesn't hold wallets in with Invalid Wallet Currency (HTTP 500), and a WalletType it doesn't recognize with <WalletType> - Invalid wallet type. Send a three-letter ISO 4217 code and Standard.
  • Your code waits for an OTP. BookExchange no longer takes a one-time password: release 4.91.2 removed it, so the exchange books in a single request, and Xtrm ignores an OTP field if you still send one.

#When the batch payment is processed

  • Items fail with INSUFFICIENT_BALANCE. The source wallet held less than the item's Amount plus its fee when Xtrm processed it, so nothing was debited for that item. Exchange more into the same wallet, then resubmit only the failed items under their original IDs, with every field as before. See Resubmit failed payments.
  • Card items in another currency. Gift card and prepaid card SKUs vary by currency, so look them up in the batch's currency with GetDigitalGiftCards or GetPrepaidCards. A gift card item (XTR94505) whose SKU is in a different currency from the batch fails during processing with CURRENCY_MISMATCH. A prepaid card item (XTR94503) fails with SKU_NOT_FOUND when its SKU isn't one of the prepaid products for the batch's currency, or with CURRENCY_INVALID when there's no prepaid product in that currency.
  • You pay in more than one currency. A batch has a single currency, shared by all its items. We recommend one batch per currency, each from a wallet in that currency. Exchange funds into each wallet with the steps in this guide.

#Next steps