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.
- POST
/API/v4/Wallet/CreateCompanyWalletCreate a company wallet - POST
/API/v4/Wallet/GetCompanyWalletsList company wallets - POST
/API/v4/Wallet/UpdateCompanyWalletRename a company wallet - POST
/API/v4/Wallet/CreateUserWalletCreate an individual recipient's wallet - POST
/API/v4/Wallet/GetUserWalletsList an individual recipient's wallets - POST
/API/v4/Wallet/GetUserWalletBalanceGet an individual recipient's wallet balance - POST
/API/v4/Wallet/UpdateUserWalletRename an individual recipient's wallet - POST
/API/v4/Wallet/CreateBeneficiaryCompanyWalletCreate a business recipient's wallet - POST
/API/v4/Wallet/GetBeneficiaryWalletsList a recipient's wallets - POST
/API/v4/Wallet/UpdateBeneficiaryCompanyWalletRename a business recipient's wallet
#Create a company wallet
/API/v4/Wallet/CreateCompanyWalletCreates 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.
Important
Use this endpoint only for your company (a remitting or managing company). For a business recipient, use CreateBeneficiaryCompanyWallet. For an individual recipient, use CreateUserWallet.
Body parameters
CreateCompanyWalletobjectRequiredWrapper object for the
CreateCompanyWalletrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters5
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.WalletNamestringRequiredA descriptive name for the wallet. Names don't have to be unique.
WalletCurrencystringRequiredThree-letter ISO 4217 currency code for the new wallet, for example
USDorEUR.WalletTypestringRequiredWallet type. Send
Standard: the field is required, andStandardis the only type to use when you create a wallet through the API. A value that isn't a wallet type fails with400and<value> - Invalid wallet typeinErrors.Allowed values:
Standard.EntityIDintegerOptionalThe ID of the entity to create the wallet in: one of your company's active entities, the same ID as
EntityIdinGetEntities. Leave it out, or send0, 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 with400and<id> - Invalid Entity IDinErrors, for example27099 - Invalid Entity ID. Leave it out rather than sending it empty:"", a negative number or anything else that isn't a whole number fails with400andEntityID must be an integer.
Response fields
CreateCompanyWalletResponseobjectResponse wrapper.
Child parameters1
CreateCompanyWalletResultobjectResult of the operation.
Child parameters4
WalletIDintegerThe globally unique identifier Xtrm generates for the new wallet.
WalletNamestringThe wallet name, matching the
WalletNameyou sent.WalletCurrencystringThree-letter ISO 4217 currency code of the new wallet.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Wallet/GetCompanyWalletsReturns 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
GetCompanyWalletsobjectRequiredWrapper object for the
GetCompanyWalletsrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters1
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.
Response fields
GetCompanyWalletResponseobjectResponse wrapper.
Child parameters1
CompanyWalletResultobjectResult of the operation.
Child parameters2
CompanyWalletsobjectContainer for the company wallets.
Child parameters1
CompanyWalletDetailsobject[]The company wallets.
Child parameters8
WalletIDintegerThe unique identifier Xtrm generated for the wallet.
WalletNamestringThe wallet's display name.
WalletCurrencystringThree-letter ISO 4217 currency code of the wallet.
WalletBalancenumberCurrent available balance of the wallet, for example
57715.15.WalletTypestringWallet classification, for example
Standard.IsBankLinkedbooleantrueif the wallet is linked to a default bank, otherwisefalse.AllowWalletLinkedBankOverridebooleanWhether a batch bank payment (
XTR94500) that names this wallet inDestination.WalletIdcan pay aBeneficiaryBankIDother than the wallet's linked bank.EntityIDintegerThe ID of the entity the wallet belongs to: one of your company's entities, the same ID as
EntityIdinGetEntities. A wallet created without anEntityIDbelongs to your company's prime entity.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: Create a company wallet · Rename a company wallet · List company wallet transactions · Exchange currency between wallets
#Rename a company wallet
/API/v4/Wallet/UpdateCompanyWalletChanges 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
UpdateCompanyWalletobjectRequiredWrapper object for the
UpdateCompanyWalletrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.WalletIDstringRequiredThe identifier Xtrm generated for the wallet you are updating. Numeric ID sent as a string, for example
"122183".WalletNamestringRequiredThe new name for the wallet. Names don't have to be unique.
Response fields
UpdateCompanyWalletResponseobjectResponse wrapper.
Child parameters1
UpdateCompanyWalletResultobjectResult of the operation.
Child parameters2
StatusstringText describing the result of the update, for example
Updated successfully.OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: List company wallets · Create a company wallet
#Create an individual recipient's wallet
/API/v4/Wallet/CreateUserWalletCreates 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.
Important
Use this endpoint only for an individual recipient. For a business recipient, use CreateBeneficiaryCompanyWallet. For your company (a remitting or managing company), use CreateCompanyWallet.
Body parameters
CreateUserWalletobjectRequiredWrapper object for the
CreateUserWalletrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters4
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.UserIDstringRequiredThe individual recipient's Xtrm account number, starting with
PAT.WalletNamestringRequiredA descriptive name for the wallet. Names don't have to be unique.
WalletCurrencystringRequiredThree-letter ISO 4217 currency code for the new wallet, for example
USDorEUR.
Response fields
CreateUserWalletResponseobjectResponse wrapper.
Child parameters1
CreateUserWalletResultobjectResult of the operation.
Child parameters4
WalletIDintegerThe globally unique identifier Xtrm generates for the new wallet.
WalletNamestringThe wallet name, matching the
WalletNameyou sent.WalletCurrencystringThree-letter ISO 4217 currency code of the new wallet.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Wallet/GetUserWalletsReturns 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
GetUserWalletsobjectRequiredWrapper object for the
GetUserWalletsrequest.Child parameters1
RequestobjectRequiredRequest details. Note the capital
RinRequest.Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.UserIDstringRequiredThe individual recipient's Xtrm account number, starting with
PAT.
Response fields
GetUserWalletsResponseobjectResponse wrapper.
Child parameters1
GetUserWalletsResultobjectResult of the operation.
Child parameters2
Walletsobject[]The individual recipient's wallets.
Child parameters3
WalletNamestringThe wallet's display name.
WalletIDintegerThe unique identifier Xtrm generated for the wallet.
WalletCurrencystringThree-letter ISO 4217 currency code of the wallet.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Wallet/GetUserWalletBalanceReturns 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
GetUserWalletBalanceobjectRequiredWrapper object for the
GetUserWalletBalancerequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.UserIdstringRequiredThe individual recipient's Xtrm account number, starting with
PAT.CurrencystringRequiredThree-letter ISO 4217 currency code of the wallet, for example
USDorEUR.
Response fields
UserWalletBalnceResponseobjectResponse wrapper.
Child parameters1
UserWalletBalanceResultobjectResult of the operation.
Child parameters3
BalancenumberCurrent available balance of the wallet, returned as a JSON number (for example
1250.43) rather than a string or integer.CurrencystringThree-letter ISO 4217 currency code of the wallet.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Wallet/UpdateUserWalletChanges 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
UpdateUserWalletobjectRequiredWrapper object for the
UpdateUserWalletrequest.Child parameters1
RequestobjectRequiredRequest details. Note the capital
RinRequest.Child parameters4
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.UserIDstringRequiredThe individual recipient's Xtrm account number, starting with
PAT.WalletIDstringRequiredThe identifier Xtrm generated for the wallet you are updating. Numeric ID sent as a string, for example
"67812".WalletNamestringRequiredThe new name for the wallet. Names don't have to be unique.
Response fields
UpdateUserWalletResponseobjectResponse wrapper.
Child parameters1
UpdateUserWalletResultobjectResult of the operation.
Child parameters2
StatusstringText describing the result of the update, for example
Updated successfully.OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: List an individual recipient's wallets · Create an individual recipient's wallet
#Create a business recipient's wallet
/API/v4/Wallet/CreateBeneficiaryCompanyWalletCreates 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.
Important
Use this endpoint only for a business recipient. For your company (a managing or remitting company), use CreateCompanyWallet. For an individual recipient, use CreateUserWallet.
Body parameters
CreateBeneficiaryCompanyWalletobjectRequiredWrapper object for the
CreateBeneficiaryCompanyWalletrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters6
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.BeneficiaryAccountNumberstringRequiredThe business recipient's Xtrm account number, starting with
SPN. The new wallet belongs to this account.WalletNamestringRequiredA descriptive name for the wallet. Names don't have to be unique.
WalletCurrencystringRequiredThree-letter ISO 4217 currency code for the new wallet, for example
USDorEUR.WalletTypestringRequiredWallet type. Send
Standard: the field is required, andStandardis the only type to use when you create a wallet through the API. A value that isn't a wallet type fails with400and<value> - Invalid wallet typeinErrors.Allowed values:
Standard.EntityIDintegerOptionalThe ID of the entity to create the wallet in: one of the business recipient's active entities, the
EntityIdthatGetEntitiesreturns for the recipient's account number. Leave it out, or send0, 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 with400and<id> - Invalid Entity IDinErrors. Leave it out rather than sending it empty:"", a negative number or anything else that isn't a whole number fails with400andEntityID must be an integer.
Response fields
CreateBeneficiaryCompanyWalletResponseobjectResponse wrapper.
Child parameters1
CreateBeneficiaryCompanyWalletResultobjectResult of the operation.
Child parameters4
WalletIDintegerThe globally unique identifier Xtrm generates for the new wallet.
WalletNamestringThe wallet name, matching the
WalletNameyou sent.WalletCurrencystringThree-letter ISO 4217 currency code of the new wallet.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Wallet/GetBeneficiaryWalletsReturns 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.
Important
If a business recipient's wallet has AllowWalletLinkedBankOverride set to false, a batch bank payment (XTR94500) that names the wallet in Destination.WalletId pays the wallet's linked bank and ignores the BeneficiaryBankID in the item.
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
GetBeneficiaryWalletsobjectRequiredWrapper object for the
GetBeneficiaryWalletsrequest.Child parameters1
requestobjectRequiredRequest details.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.BeneficiaryAccountNumberstringRequiredThe recipient's Xtrm account number:
SPNfor a business recipient orPATfor an individual recipient.
Response fields
GetBeneficiaryWalletsResponseobjectResponse wrapper.
Child parameters1
GetBeneficiaryWalletsResultobjectResult of the operation.
Child parameters2
Walletsobject[]The recipient's wallets.
Child parameters8
NamestringThe wallet's display name.
IDintegerThe unique identifier Xtrm generated for the wallet.
CurrencystringThree-letter ISO 4217 currency code of the wallet.
TypestringWallet classification, for example
Standard.BalancenumberCurrent available balance of the wallet, for example
2520.23.IsBankLinkedbooleantrueif a bank account is linked to the wallet as its default bank, otherwisefalse.AllowWalletLinkedBankOverridebooleanWhether a batch bank payment (
XTR94500) that names this wallet inDestination.WalletIdcan pay aBeneficiaryBankIDother than the wallet's linked bank.EntityIDintegerThe ID of the entity the wallet belongs to, or
0if it has none. For a business recipient, it is one of the recipient's entities, the same ID asEntityIdinGetEntities.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Wallet/UpdateBeneficiaryCompanyWalletChanges 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
UpdateBeneficiaryCompanyWalletobjectRequiredWrapper object for the
UpdateBeneficiaryCompanyWalletrequest.Child parameters1
RequestobjectRequiredRequest details. Note the capital
RinRequest.Child parameters4
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.BeneficiaryAccountNumberstringRequiredThe business recipient's Xtrm account number, starting with
SPN.WalletIDstringRequiredThe identifier Xtrm generated for the wallet you are updating. Numeric ID sent as a string, for example
"122341".WalletNamestringRequiredThe new name for the wallet. Names don't have to be unique.
Response fields
UpdateBeneficiaryCompanyWalletResponseobjectResponse wrapper.
Child parameters1
UpdateBeneficiaryCompanyWalletResultobjectResult of the operation.
Child parameters2
StatusstringText describing the result of the update, for example
Updated successfully.OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
Related: List a recipient's wallets · Create a business recipient's wallet