Core concepts

Connections and manager services

You can pay any Xtrm account without asking anyone first. A connection is for everything after that. It's the account holder's go-ahead for your company to manage more for them: their wallets, their bank accounts and cards, their profile, and transfers out of their wallets.

Manager services go a step further, in the Xtrm web app. Xtrm turns them on for your company, and they let you do more for an account you're connected to, from submitting a connected company's advanced profile to getting its API credentials.

From your company's side, every other account sits at one of three levels:

  • Not connected. You can find the account, see its identity verification level and pay it in a batch.
  • Connected. Your company can also manage the account's wallets, bank accounts, cards and profile, and start transfers out of its wallets with the account holder's one-time password. In the API, no call that acts on another account needs more than this.
  • Connected, with manager services. In the Xtrm web app, your company can do more for a connected account, such as upload a connected company's identity documents, which no API call can do. Pseudo credentials need this level too.

Connections and pseudo credentials do different jobs. A connection lets the company making a call act on another account, such as linking a bank account for a recipient. Pseudo credentials let a managing platform act as a client company.

#How accounts become connected

In the API, an account is connected to your company as soon as:

Connecting also adds the account to your recipient list, the one GetPersonalBeneficiaries and GetBeneficiaries return.

If you're a managing platform acting with a client company's pseudo credentials, an account you create is connected to the client company and to your platform. A business you connect with a one-time password is connected to both as well, and a person is connected to the client company only.

In the Xtrm web app:

  • Pay someone new. When you pay a person or business that doesn't have an Xtrm account yet, the web app creates the account and connects it to your company at once. This path is in the web app only: an API batch pays existing account numbers, and never creates or connects an account.
  • Send a connection request. To connect a company that already has an account, open Contacts > Connected Companies and send it a connection request. The request shows as Pending until it's approved.

#What the account holder agrees to

When you ask someone to connect, tell them what it means. This wording matches what a connection allows in the API:

Connecting your Xtrm account gives [your company] access to your wallets and wallet activity, your bank accounts and cards, and your profile. [Your company] can also start transfers out of your wallets, and each transfer needs a one-time password from you.

Paying the account doesn't need a connection, so there's no need to ask for one just to pay someone.

#Check a connection

GetConnectedStatus returns the connection between your company and an account in Status:

StatusMeans
ConnectedThe account is connected to your company.
PendingA connection request sent in the web app hasn't been approved yet.
CancelledA connection request was cancelled before it was approved.
Not ConnectedThere's no connection: the account was never connected, a request was declined, or the connection ended.

Only an exact Connected lets your company act on the account. Compare Status to Connected exactly, since Not Connected contains the word Connected.

A Pending connection doesn't let your company do anything a Not Connected one can't. If you don't want to wait for the request to be approved, connect the account with a one-time password instead: the account is connected as soon as you validate the code.

#Icons in the web app

In the Xtrm web app, icons next to a company's name show where it stands:

IconMeans
Blue linkThe company is connected to yours (Connected Account).
Red starThe company is a manager account (Manager Approved).
Gold starXtrm has approved the company for Advanced Services (Advanced Services Approved).

You'll see them in Contacts > Company Contacts, in your list of connected companies and at the top of a connected company's pages. To list only some companies, filter the list by Connected, Advanced Services or Manager Accounts.

#How a connection ends

A connection lasts until it's disconnected in the Xtrm web app: by your company, by the connected company or by Xtrm. No API call ends a connection.

Once a connection ends, GetConnectedStatus returns Not Connected and every call that needs the connection fails. Disconnecting also stops any pseudo credentials between the two companies, along with their tokens. The account stays in your recipient list, you can still pay it in a batch, and you can connect it again with a one-time password.

#What a connection allows

Manager services decide what your company can do for a connected account in the Xtrm web app. In the API, a connection is all a call needs: every call that acts on another account works once the account is connected to your company. The one exception is pseudo credentials, which require manager services.

#In the API

What your company can doNot connectedConnectedConnected + manager services
Pay the account in a batch (BatchTransfer)YesYesYes
Find the account by email address, or a business by email domain or name, with its status and identity verification level (CheckUserExist, CheckBeneficiaryExist)YesYesYes
List it among your recipients (GetPersonalBeneficiaries, GetBeneficiaries)Once you've created or paid itYesYes
Check the connection (GetConnectedStatus)YesYesYes
List a person's wallets, without balances (GetUserWallets)YesYesYes
See the payments your company made to a person (GetUserWalletTransactionsByRemitter)YesYesYes
See a person's wallet balance (GetUserWalletBalance)NoYesYes
See all of a person's wallet activity, not only your payments (GetUserWalletTransactions, GetUserWalletTransactionDetails)NoYesYes
Create or rename a person's wallet (CreateUserWallet, UpdateUserWallet)NoYesYes
Create a business's wallet (CreateBeneficiaryCompanyWallet)NoYesYes
Rename a business's wallet (UpdateBeneficiaryCompanyWallet)Once you've created or paid itYesYes
See a business's credit and debit totals (GetConnectedCompanyFundRequest) and its fees (GetCompanyFees)NoYesYes
Fund a business's wallet by bank transfer (FundWalletUsingBankTransfer)NoYesYes
Exchange currency between the account's wallets (BookExchange)NoYesYes
Link a bank account for the account (LinkBankBeneficiary). The account holder sees it in their own list.NoYesYes
List the account's bank accounts, whoever linked them (GetLinkedBankAccounts)NoYesYes
Delete one of the account's bank accounts (DeleteBankBeneficiary)NoYesYes
Link or list the account's bank-debit banks (LinkACHDebitBankBeneficiary, GetACHDebitLinkedBankAccounts)NoYesYes
Link, list or delete the account's cards (LinkCard, GetLinkedCards, DeleteCard)NoYesYes
Update a person's legal name, address, date of birth, tax ID and mobile number (UpdateUser)NoYesYes
Update a business's profile (UpdateBeneficiary) and list its entities (GetEntities)NoYesYes
Submit and read a company's advanced profile (CompanyAdvancedProfile, GetCompanyAdvancedProfileDetails)NoYesYes
Email a person their tax forms (TransferTaxInformation)NoYesYes
Transfer money out of the account's wallet (UserWithdrawFund, BeneficiaryCompanyWithdrawFund)NoWith the account holder's one-time password for each transferWith the account holder's one-time password for each transfer
Act as a company with its pseudo credentialsNoNoYes

A few rows need a word more:

  • Paying doesn't need a connection, and doesn't make one. After a payment completes, the account appears in your recipient list. A payment to a bank account or card needs that bank or card linked to the recipient, and linking or looking one up needs a connection. An account you created is already connected.
  • Wallet activity. Without a connection, GetUserWalletTransactionsByRemitter with your own SPN in RemitterAccountNo shows the payments your company made to a person. Once you're connected, GetUserWalletTransactions shows all of their wallet activity.
  • A person's email address. UpdateUser has no email field. To change a connected person's email address, use the Xtrm web app, where it's a manager service.
  • Transfers out of the account. Each one needs a one-time password that Xtrm sends to the account holder for that transfer. See Bank accounts & transfers.

A call that needs a connection fails without one, with HTTP 400 or 401 and an error such as Not authorized to access this resource. Make One Time Password API Call to access this resource.

#In the Xtrm web app

What your company can doNot connectedConnectedConnected + manager services
Pay the accountYesYesYes
View a company's wallets and its adminsYesYesYes
View the account's identity verification level and identity summaryNoYesYes
View the account's linked bank accountsNoYes, all of themYes
Link a bank account the account holder doesn't see. It doesn't appear in GetLinkedBankAccounts either.NoYesYes
Link a bank account the account holder also sees (Link Bank)NoNoYes
Delete one of the account's bank accountsNoNoYes
View a connected company's wallet activityNoYes, except its sends and transfersSends and transfers too, each a separate manager service
Create a connected company's walletsNoNoYes
Create a fund request for a connected company's walletNoNoYes, once Xtrm has approved the company's advanced profile
Get a connected company's funding bank details (Get Funding Bank Details)NoNoYes
Submit a connected company's advanced profile (Advanced Services Application)NoNoYes
Edit a connected company's organization details, address and logo (Identity Profile, Organization Setup)NoNoYes
Upload, view and expire a connected company's identity documents, such as its administrator's photo ID and its tax document (Identity Documents). No API call uploads documents.NoNoYes, for a Master Admin or Controller
Customize a connected company's alert emails (Customize Email Alerts)NoNoYes
Submit a payment file for a connected companyNoNoYes
Edit a connected person's email address, employer or mobile numberNoNoYes, each a separate manager service
Connect personal accounts to a connected company, from its Individuals tabNoNoYes
Get a connected company's API credentials, its pseudo credentials (Get API Credentials)NoNoYes

#Manager services

Xtrm turns each manager service on for your company separately, so tell Xtrm which ones you need.

A manager service works only for an account that's connected to your company and active, and only for your master admin or the team members you give the Connected Manager Services permission. For a connected company, you'll find them in its Connected Manager Services menu, on its profile and other pages you open from Contacts > Company Contacts.

Identity Documents is the manager service that lets your platform upload a client company's documents for it. A company needs its documents on file to reach Advanced, and no API call uploads documents, so they go through the web app: your platform uploads them from the company's Connected Manager Services menu, or the company uploads them from its own account. See Onboard a client company.

Pseudo credentials require manager services: Xtrm has to turn manager services on for your company before you can get or use a client company's pseudo credentials. Pseudo credentials shows where to get them.

#Calls that name two accounts

Many calls act on a second account besides the one in IssuerAccountNumber:

  • IssuerAccountNumber is always the SPN tied to the credentials you use: your own company's, or a client company's when you use its pseudo credentials.
  • The second field names the account the call acts on. For most of these calls, that account has to be connected to the company in IssuerAccountNumber.
CallSecond account fieldNeeds a connection
LinkBankBeneficiaryUserIDYes
GetLinkedBankAccountsRecipientUserIdYes
DeleteBankBeneficiaryRecipientAccountNumberYes
LinkACHDebitBankBeneficiaryUserIDYes
GetACHDebitLinkedBankAccountsRecipientUserIdYes
LinkCard, DeleteCardUserIDYes
GetLinkedCardsuseridYes
GetUserWalletBalanceUserIdYes
CreateUserWallet, UpdateUserWalletUserIDYes
GetUserWalletTransactions, GetUserWalletTransactionDetailsUserIDYes
CreateBeneficiaryCompanyWalletBeneficiaryAccountNumberYes
UpdateUserUserIdYes
UpdateBeneficiaryBeneficiaryIDYes
GetEntitiesUserIDYes
CompanyAdvancedProfile, GetCompanyAdvancedProfileDetailsBeneficiaryAccountNumberYes
GetConnectedCompanyFundRequest, GetCompanyFees, TransferTaxInformationBeneficiaryAccountNumberYes
FundWalletUsingBankTransferBeneficiaryAccountNumberYes
BookExchangeAccountNumberYes
UserWithdrawFundUserIDYes, plus the account holder's one-time password
BeneficiaryCompanyWithdrawFundBeneficiaryAccountNumberYes, plus the account holder's one-time password
UpdateBeneficiaryCompanyWalletBeneficiaryAccountNumberNo: it works for a business you created, paid or are connected to
GetUserWalletsUserIDNo
GetUserWalletTransactionsByRemitterUserID, with your own SPN in RemitterAccountNoNo
GetConnectedStatusUserIDNo
GetOTPAuthorizedVendor, ValidateOTPAuthorizeVendorRecipientUserId, RecipientUserIDNo: these calls make the connection
BatchTransferRecipientId, in each itemNo

Some of these calls also take your own SPN in the second field, for your own company's bank accounts, cards or wallets. No connection is involved then.

For example, a managing platform that wants to link a bank account for a client company's recipient uses the client company's pseudo credentials: the client company's SPN in IssuerAccountNumber and the recipient's account number in UserID. The recipient has to be connected to the client company, which it is if the client company created it. To link a bank account for one of your own recipients, send your own SPN in IssuerAccountNumber instead.

#Next steps