API reference

Wallets

A wallet holds money in one currency for an Xtrm account. Xtrm generates each wallet's WalletID, and you choose its currency and a display name. Names don't have to be unique, so identify wallets by WalletID. After you create a wallet, you can change only its name: the WalletID and currency stay fixed.

Each account type has its own endpoint for creating wallets: CreateCompanyWallet for your company (a remitting or managing company), CreateBeneficiaryCompanyWallet for a business recipient (SPN), and CreateUserWallet for an individual recipient (PAT). A company can hold more than one wallet per currency. An individual recipient can hold one wallet per currency.

When you create a wallet for your company or for a business recipient, set its WalletType to Standard. The field is required, and Standard is the only type to use when you create a wallet through the API.

#Create a company wallet

POST/API/v4/Wallet/CreateCompanyWallet

Creates a wallet for your company (a remitting or managing company), with a name and currency. A company can hold more than one wallet per currency.

Names don't have to be unique, so we recommend a distinct name for each wallet and identifying wallets by WalletID. Set WalletType to Standard.

The wallet goes into your company's prime entity, its default, unless you name another of your company's entities in EntityID. See Entity IDs.

The response returns the WalletID that Xtrm generates for the new wallet.

Body parameters

  • CreateCompanyWalletobjectRequired

    Wrapper object for the CreateCompanyWallet request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters5
      • 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.

      • WalletNamestringRequired

        A descriptive name for the wallet. Names don't have to be unique.

      • WalletCurrencystringRequired

        Three-letter ISO 4217 currency code for the new wallet, for example USD or EUR.

      • WalletTypestringRequired

        Wallet type. Send Standard: the field is required, and Standard is the only type to use when you create a wallet through the API. A value that isn't a wallet type fails with 400 and <value> - Invalid wallet type in Errors.

        Allowed values: Standard.

      • EntityIDintegerOptional

        The ID of the entity to create the wallet in: one of your company's active entities, the same ID as EntityId in GetEntities. Leave it out, or send 0, to create the wallet in your company's prime entity, its default. Any other value must be one of your company's active entities, or the call fails with 400 and <id> - Invalid Entity ID in Errors, for example 27099 - Invalid Entity ID. Leave it out rather than sending it empty: "", a negative number or anything else that isn't a whole number fails with 400 and EntityID must be an integer.

Response fields

  • CreateCompanyWalletResponseobject

    Response wrapper.

    Child parameters1
    • CreateCompanyWalletResultobject

      Result of the operation.

      Child parameters4
      • WalletIDinteger

        The globally unique identifier Xtrm generates for the new wallet.

      • WalletNamestring

        The wallet name, matching the WalletName you sent.

      • WalletCurrencystring

        Three-letter ISO 4217 currency code of the new wallet.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List company wallets · Rename a company wallet · Fund a wallet by bank transfer · Fund a wallet with a credit card · Fund a wallet by bank debit · List your organization's entities

#List company wallets

POST/API/v4/Wallet/GetCompanyWallets

Returns the wallets of the company in IssuerAccountNumber.

Each wallet in CompanyWalletDetails includes its WalletID, name, currency, balance and WalletType (for example Standard), and the EntityID of the entity it belongs to. Two flags describe its bank: IsBankLinked says whether a bank is linked to the wallet, and AllowWalletLinkedBankOverride says whether that linked bank can be overridden. Use the WalletID to refer to the wallet in other calls, such as UpdateCompanyWallet.

Note

IsBankLinked is true when the wallet is linked to a default bank. AllowWalletLinkedBankOverride applies only to batch bank payments (XTR94500) to a business that name the business's wallet in Destination.WalletId. When the flag is true, Xtrm pays the BeneficiaryBankID in the item, or the wallet's linked bank when the item has none. When it's false, Xtrm always pays the wallet's linked bank, whatever BeneficiaryBankID the item names. If no bank applies, the payment fails with DEFAULT_BANK_NOT_FOUND. Transfers out of a wallet with BeneficiaryCompanyWithdrawFund always pay the bank you name in the request.

Tip

In the sandbox, once your IPs are approved, Xtrm adds USD 5,000 (and 5,000 in your local currency, if you ask for it) to the wallets in your sandbox testing account.

Body parameters

  • GetCompanyWalletsobjectRequired

    Wrapper object for the GetCompanyWallets request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters1
      • 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.

Response fields

  • GetCompanyWalletResponseobject

    Response wrapper.

    Child parameters1
    • CompanyWalletResultobject

      Result of the operation.

      Child parameters2
      • CompanyWalletsobject

        Container for the company wallets.

        Child parameters1
        • CompanyWalletDetailsobject[]

          The company wallets.

          Child parameters8
          • WalletIDinteger

            The unique identifier Xtrm generated for the wallet.

          • WalletNamestring

            The wallet's display name.

          • WalletCurrencystring

            Three-letter ISO 4217 currency code of the wallet.

          • WalletBalancenumber

            Current available balance of the wallet, for example 57715.15.

          • WalletTypestring

            Wallet classification, for example Standard.

          • IsBankLinkedboolean

            true if the wallet is linked to a default bank, otherwise false.

          • AllowWalletLinkedBankOverrideboolean

            Whether a batch bank payment (XTR94500) that names this wallet in Destination.WalletId can pay a BeneficiaryBankID other than the wallet's linked bank.

          • EntityIDinteger

            The ID of the entity the wallet belongs to: one of your company's entities, the same ID as EntityId in GetEntities. A wallet created without an EntityID belongs to your company's prime entity.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Create a company wallet · Rename a company wallet · List company wallet transactions · Exchange currency between wallets

#Rename a company wallet

POST/API/v4/Wallet/UpdateCompanyWallet

Changes the name of one of your company's wallets. Identify the wallet by its WalletID and pass the new WalletName.

Note

You can change only the wallet name. A wallet's WalletID and currency can't be changed.

Body parameters

  • UpdateCompanyWalletobjectRequired

    Wrapper object for the UpdateCompanyWallet request.

    Child parameters1
    • requestobjectRequired

      Request details.

      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.

      • WalletIDstringRequired

        The identifier Xtrm generated for the wallet you are updating. Numeric ID sent as a string, for example "122183".

      • WalletNamestringRequired

        The new name for the wallet. Names don't have to be unique.

Response fields

  • UpdateCompanyWalletResponseobject

    Response wrapper.

    Child parameters1
    • UpdateCompanyWalletResultobject

      Result of the operation.

      Child parameters2
      • Statusstring

        Text describing the result of the update, for example Updated successfully.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List company wallets · Create a company wallet

#Create an individual recipient's wallet

POST/API/v4/Wallet/CreateUserWallet

Creates a wallet for an individual recipient (personal account, PAT), with a name and currency.

An individual recipient can have several wallets, but only one per currency: a wallet in a currency the recipient already holds isn't created, and the call fails with 500 and Wallet exist for this currency. CreateUser already creates a wallet in the currency of the recipient's country. Names don't have to be unique, so we recommend a distinct name for each wallet and identifying wallets by WalletID. The response returns the WalletID that Xtrm generates for the new wallet.

Your company must be connected to the recipient. You're connected to every recipient you create; to connect an account that already exists, see Connect existing accounts.

Body parameters

  • CreateUserWalletobjectRequired

    Wrapper object for the CreateUserWallet request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters4
      • 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.

      • UserIDstringRequired

        The individual recipient's Xtrm account number, starting with PAT.

      • WalletNamestringRequired

        A descriptive name for the wallet. Names don't have to be unique.

      • WalletCurrencystringRequired

        Three-letter ISO 4217 currency code for the new wallet, for example USD or EUR.

Response fields

  • CreateUserWalletResponseobject

    Response wrapper.

    Child parameters1
    • CreateUserWalletResultobject

      Result of the operation.

      Child parameters4
      • WalletIDinteger

        The globally unique identifier Xtrm generates for the new wallet.

      • WalletNamestring

        The wallet name, matching the WalletName you sent.

      • WalletCurrencystring

        Three-letter ISO 4217 currency code of the new wallet.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Create an individual recipient · List an individual recipient's wallets · Rename an individual recipient's wallet · Get an individual recipient's wallet balance

#List an individual recipient's wallets

POST/API/v4/Wallet/GetUserWallets

Returns the wallets of an individual recipient (personal account, PAT). Each wallet includes its WalletID, WalletName and WalletCurrency.

This call doesn't need a connection to the recipient, so you can use it to pick the wallet for a batch item. See Connections and manager services.

Tip

The response doesn't include balances. To get a wallet's balance, call GetUserWalletBalance.

Body parameters

  • GetUserWalletsobjectRequired

    Wrapper object for the GetUserWallets request.

    Child parameters1
    • RequestobjectRequired

      Request details. Note the capital R in Request.

      Child parameters2
      • 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.

      • UserIDstringRequired

        The individual recipient's Xtrm account number, starting with PAT.

Response fields

  • GetUserWalletsResponseobject

    Response wrapper.

    Child parameters1
    • GetUserWalletsResultobject

      Result of the operation.

      Child parameters2
      • Walletsobject[]

        The individual recipient's wallets.

        Child parameters3
        • WalletNamestring

          The wallet's display name.

        • WalletIDinteger

          The unique identifier Xtrm generated for the wallet.

        • WalletCurrencystring

          Three-letter ISO 4217 currency code of the wallet.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Create an individual recipient's wallet · Get an individual recipient's wallet balance · Rename an individual recipient's wallet · List an individual recipient's wallet transactions

#Get an individual recipient's wallet balance

POST/API/v4/Wallet/GetUserWalletBalance

Returns the balance of an individual recipient's (PAT) wallet in the currency you pass in Currency. An individual recipient can hold only one wallet per currency.

Balance comes back as a JSON number, for example 1250.43, not as a string.

Your company must be connected to the recipient. You're connected to every recipient you create; to connect an account that already exists, see Connect existing accounts.

Body parameters

  • GetUserWalletBalanceobjectRequired

    Wrapper object for the GetUserWalletBalance request.

    Child parameters1
    • requestobjectRequired

      Request details.

      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.

      • UserIdstringRequired

        The individual recipient's Xtrm account number, starting with PAT.

      • CurrencystringRequired

        Three-letter ISO 4217 currency code of the wallet, for example USD or EUR.

Response fields

  • UserWalletBalnceResponseobject

    Response wrapper.

    Child parameters1
    • UserWalletBalanceResultobject

      Result of the operation.

      Child parameters3
      • Balancenumber

        Current available balance of the wallet, returned as a JSON number (for example 1250.43) rather than a string or integer.

      • Currencystring

        Three-letter ISO 4217 currency code of the wallet.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List an individual recipient's wallets · List an individual recipient's wallet transactions · Transfer from an individual recipient's wallet

#Rename an individual recipient's wallet

POST/API/v4/Wallet/UpdateUserWallet

Changes the name of an individual recipient's (PAT) wallet. Identify the recipient by UserID and the wallet by WalletID, and pass the new WalletName.

Your company must be connected to the recipient. You're connected to every recipient you create; to connect an account that already exists, see Connect existing accounts.

Note

You can change only the wallet name. A wallet's WalletID and currency can't be changed.

Body parameters

  • UpdateUserWalletobjectRequired

    Wrapper object for the UpdateUserWallet request.

    Child parameters1
    • RequestobjectRequired

      Request details. Note the capital R in Request.

      Child parameters4
      • 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.

      • UserIDstringRequired

        The individual recipient's Xtrm account number, starting with PAT.

      • WalletIDstringRequired

        The identifier Xtrm generated for the wallet you are updating. Numeric ID sent as a string, for example "67812".

      • WalletNamestringRequired

        The new name for the wallet. Names don't have to be unique.

Response fields

  • UpdateUserWalletResponseobject

    Response wrapper.

    Child parameters1
    • UpdateUserWalletResultobject

      Result of the operation.

      Child parameters2
      • Statusstring

        Text describing the result of the update, for example Updated successfully.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List an individual recipient's wallets · Create an individual recipient's wallet

#Create a business recipient's wallet

POST/API/v4/Wallet/CreateBeneficiaryCompanyWallet

Creates a wallet for a business recipient (SPN), with a name and currency. A company can hold more than one wallet per currency.

Names don't have to be unique, so we recommend a distinct name for each wallet and identifying wallets by WalletID. Set WalletType to Standard.

The wallet goes into the business recipient's prime entity, its default, unless you name another of the recipient's entities in EntityID. To list the recipient's entities, call GetEntities with the recipient's account number in UserID. See Entity IDs.

Your company must be connected to the recipient. You're connected to every recipient you create; to connect an account that already exists, see Connect existing accounts.

The response returns the WalletID that Xtrm generates for the new wallet.

Body parameters

  • CreateBeneficiaryCompanyWalletobjectRequired

    Wrapper object for the CreateBeneficiaryCompanyWallet request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters6
      • 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.

      • BeneficiaryAccountNumberstringRequired

        The business recipient's Xtrm account number, starting with SPN. The new wallet belongs to this account.

      • WalletNamestringRequired

        A descriptive name for the wallet. Names don't have to be unique.

      • WalletCurrencystringRequired

        Three-letter ISO 4217 currency code for the new wallet, for example USD or EUR.

      • WalletTypestringRequired

        Wallet type. Send Standard: the field is required, and Standard is the only type to use when you create a wallet through the API. A value that isn't a wallet type fails with 400 and <value> - Invalid wallet type in Errors.

        Allowed values: Standard.

      • EntityIDintegerOptional

        The ID of the entity to create the wallet in: one of the business recipient's active entities, the EntityId that GetEntities returns for the recipient's account number. Leave it out, or send 0, to create the wallet in the recipient's prime entity, its default. Any other value must be one of the recipient's active entities, or the call fails with 400 and <id> - Invalid Entity ID in Errors. Leave it out rather than sending it empty: "", a negative number or anything else that isn't a whole number fails with 400 and EntityID must be an integer.

Response fields

  • CreateBeneficiaryCompanyWalletResponseobject

    Response wrapper.

    Child parameters1
    • CreateBeneficiaryCompanyWalletResultobject

      Result of the operation.

      Child parameters4
      • WalletIDinteger

        The globally unique identifier Xtrm generates for the new wallet.

      • WalletNamestring

        The wallet name, matching the WalletName you sent.

      • WalletCurrencystring

        Three-letter ISO 4217 currency code of the new wallet.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Create a business recipient · List a recipient's wallets · Rename a business recipient's wallet · Transfer from a business recipient's wallet · List your organization's entities

#List a recipient's wallets

POST/API/v4/Wallet/GetBeneficiaryWallets

Returns the wallets of a recipient: a business recipient (SPN) or an individual recipient (PAT).

Each wallet includes its ID, Name, Currency, Type and Balance, and the EntityID of the entity it belongs to. Two flags describe its bank: IsBankLinked says whether a bank is linked to the wallet, and AllowWalletLinkedBankOverride says whether a batch bank payment that names the wallet can pay another bank. Check both flags before a batch bank payment names this wallet in Destination.WalletId.

See Connections and manager services for what your company can do for a recipient it's connected to.

Note

IsBankLinked is true when the wallet is linked to a default bank. AllowWalletLinkedBankOverride applies only to batch bank payments (XTR94500) to a business recipient that name the wallet in Destination.WalletId. When the flag is true, Xtrm pays the BeneficiaryBankID in the item, or the wallet's linked bank when the item has none. When it's false, Xtrm always pays the wallet's linked bank. If no bank applies, the payment fails with DEFAULT_BANK_NOT_FOUND. To pay a specific bank, leave WalletId out and send its BeneficiaryBankID. Transfers out of a wallet with BeneficiaryCompanyWithdrawFund always pay the bank you name in the request.

Body parameters

  • GetBeneficiaryWalletsobjectRequired

    Wrapper object for the GetBeneficiaryWallets request.

    Child parameters1
    • requestobjectRequired

      Request details.

      Child parameters2
      • 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.

      • BeneficiaryAccountNumberstringRequired

        The recipient's Xtrm account number: SPN for a business recipient or PAT for an individual recipient.

Response fields

  • GetBeneficiaryWalletsResponseobject

    Response wrapper.

    Child parameters1
    • GetBeneficiaryWalletsResultobject

      Result of the operation.

      Child parameters2
      • Walletsobject[]

        The recipient's wallets.

        Child parameters8
        • Namestring

          The wallet's display name.

        • IDinteger

          The unique identifier Xtrm generated for the wallet.

        • Currencystring

          Three-letter ISO 4217 currency code of the wallet.

        • Typestring

          Wallet classification, for example Standard.

        • Balancenumber

          Current available balance of the wallet, for example 2520.23.

        • IsBankLinkedboolean

          true if a bank account is linked to the wallet as its default bank, otherwise false.

        • AllowWalletLinkedBankOverrideboolean

          Whether a batch bank payment (XTR94500) that names this wallet in Destination.WalletId can pay a BeneficiaryBankID other than the wallet's linked bank.

        • EntityIDinteger

          The ID of the entity the wallet belongs to, or 0 if it has none. For a business recipient, it is one of the recipient's entities, the same ID as EntityId in GetEntities.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Create a business recipient's wallet · Rename a business recipient's wallet · Transfer from a business recipient's wallet · Transfer from an individual recipient's wallet · Link a bank account to a recipient · List a recipient's linked bank accounts

#Rename a business recipient's wallet

POST/API/v4/Wallet/UpdateBeneficiaryCompanyWallet

Changes the display name of a business recipient's wallet. Identify the business recipient by BeneficiaryAccountNumber and the wallet by WalletID, and pass the new WalletName.

It works for a business recipient your company created, paid or is connected to. See Connections and manager services.

Note

You can change only the wallet name. A wallet's WalletID and currency can't be changed.

Body parameters

  • UpdateBeneficiaryCompanyWalletobjectRequired

    Wrapper object for the UpdateBeneficiaryCompanyWallet request.

    Child parameters1
    • RequestobjectRequired

      Request details. Note the capital R in Request.

      Child parameters4
      • 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.

      • BeneficiaryAccountNumberstringRequired

        The business recipient's Xtrm account number, starting with SPN.

      • WalletIDstringRequired

        The identifier Xtrm generated for the wallet you are updating. Numeric ID sent as a string, for example "122341".

      • WalletNamestringRequired

        The new name for the wallet. Names don't have to be unique.

Response fields

  • UpdateBeneficiaryCompanyWalletResponseobject

    Response wrapper.

    Child parameters1
    • UpdateBeneficiaryCompanyWalletResultobject

      Result of the operation.

      Child parameters2
      • Statusstring

        Text describing the result of the update, for example Updated successfully.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: List a recipient's wallets · Create a business recipient's wallet