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:
- you create it with
CreateUserorCreateBeneficiary; or - its holder gives you the one-time password that
GetOTPAuthorizedVendorsends them, and you confirm it withValidateOTPAuthorizeVendor. Connect existing accounts walks through it.
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
Pendinguntil 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:
Status | Means |
|---|---|
Connected | The account is connected to your company. |
Pending | A connection request sent in the web app hasn't been approved yet. |
Cancelled | A connection request was cancelled before it was approved. |
Not Connected | There'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:
| Icon | Means |
|---|---|
| Blue link | The company is connected to yours (Connected Account). |
| Red star | The company is a manager account (Manager Approved). |
| Gold star | Xtrm 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 do | Not connected | Connected | Connected + manager services |
|---|---|---|---|
Pay the account in a batch (BatchTransfer) | Yes | Yes | Yes |
Find the account by email address, or a business by email domain or name, with its status and identity verification level (CheckUserExist, CheckBeneficiaryExist) | Yes | Yes | Yes |
List it among your recipients (GetPersonalBeneficiaries, GetBeneficiaries) | Once you've created or paid it | Yes | Yes |
Check the connection (GetConnectedStatus) | Yes | Yes | Yes |
List a person's wallets, without balances (GetUserWallets) | Yes | Yes | Yes |
See the payments your company made to a person (GetUserWalletTransactionsByRemitter) | Yes | Yes | Yes |
See a person's wallet balance (GetUserWalletBalance) | No | Yes | Yes |
See all of a person's wallet activity, not only your payments (GetUserWalletTransactions, GetUserWalletTransactionDetails) | No | Yes | Yes |
Create or rename a person's wallet (CreateUserWallet, UpdateUserWallet) | No | Yes | Yes |
Create a business's wallet (CreateBeneficiaryCompanyWallet) | No | Yes | Yes |
Rename a business's wallet (UpdateBeneficiaryCompanyWallet) | Once you've created or paid it | Yes | Yes |
See a business's credit and debit totals (GetConnectedCompanyFundRequest) and its fees (GetCompanyFees) | No | Yes | Yes |
Fund a business's wallet by bank transfer (FundWalletUsingBankTransfer) | No | Yes | Yes |
Exchange currency between the account's wallets (BookExchange) | No | Yes | Yes |
Link a bank account for the account (LinkBankBeneficiary). The account holder sees it in their own list. | No | Yes | Yes |
List the account's bank accounts, whoever linked them (GetLinkedBankAccounts) | No | Yes | Yes |
Delete one of the account's bank accounts (DeleteBankBeneficiary) | No | Yes | Yes |
Link or list the account's bank-debit banks (LinkACHDebitBankBeneficiary, GetACHDebitLinkedBankAccounts) | No | Yes | Yes |
Link, list or delete the account's cards (LinkCard, GetLinkedCards, DeleteCard) | No | Yes | Yes |
Update a person's legal name, address, date of birth, tax ID and mobile number (UpdateUser) | No | Yes | Yes |
Update a business's profile (UpdateBeneficiary) and list its entities (GetEntities) | No | Yes | Yes |
Submit and read a company's advanced profile (CompanyAdvancedProfile, GetCompanyAdvancedProfileDetails) | No | Yes | Yes |
Email a person their tax forms (TransferTaxInformation) | No | Yes | Yes |
Transfer money out of the account's wallet (UserWithdrawFund, BeneficiaryCompanyWithdrawFund) | No | With the account holder's one-time password for each transfer | With the account holder's one-time password for each transfer |
| Act as a company with its pseudo credentials | No | No | Yes |
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,
GetUserWalletTransactionsByRemitterwith your ownSPNinRemitterAccountNoshows the payments your company made to a person. Once you're connected,GetUserWalletTransactionsshows all of their wallet activity. - A person's email address.
UpdateUserhas 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 do | Not connected | Connected | Connected + manager services |
|---|---|---|---|
| Pay the account | Yes | Yes | Yes |
| View a company's wallets and its admins | Yes | Yes | Yes |
| View the account's identity verification level and identity summary | No | Yes | Yes |
| View the account's linked bank accounts | No | Yes, all of them | Yes |
Link a bank account the account holder doesn't see. It doesn't appear in GetLinkedBankAccounts either. | No | Yes | Yes |
| Link a bank account the account holder also sees (Link Bank) | No | No | Yes |
| Delete one of the account's bank accounts | No | No | Yes |
| View a connected company's wallet activity | No | Yes, except its sends and transfers | Sends and transfers too, each a separate manager service |
| Create a connected company's wallets | No | No | Yes |
| Create a fund request for a connected company's wallet | No | No | Yes, once Xtrm has approved the company's advanced profile |
| Get a connected company's funding bank details (Get Funding Bank Details) | No | No | Yes |
| Submit a connected company's advanced profile (Advanced Services Application) | No | No | Yes |
| Edit a connected company's organization details, address and logo (Identity Profile, Organization Setup) | No | No | Yes |
| 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. | No | No | Yes, for a Master Admin or Controller |
| Customize a connected company's alert emails (Customize Email Alerts) | No | No | Yes |
| Submit a payment file for a connected company | No | No | Yes |
| Edit a connected person's email address, employer or mobile number | No | No | Yes, each a separate manager service |
| Connect personal accounts to a connected company, from its Individuals tab | No | No | Yes |
| Get a connected company's API credentials, its pseudo credentials (Get API Credentials) | No | No | Yes |
#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:
IssuerAccountNumberis always theSPNtied 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.
| Call | Second account field | Needs a connection |
|---|---|---|
LinkBankBeneficiary | UserID | Yes |
GetLinkedBankAccounts | RecipientUserId | Yes |
DeleteBankBeneficiary | RecipientAccountNumber | Yes |
LinkACHDebitBankBeneficiary | UserID | Yes |
GetACHDebitLinkedBankAccounts | RecipientUserId | Yes |
LinkCard, DeleteCard | UserID | Yes |
GetLinkedCards | userid | Yes |
GetUserWalletBalance | UserId | Yes |
CreateUserWallet, UpdateUserWallet | UserID | Yes |
GetUserWalletTransactions, GetUserWalletTransactionDetails | UserID | Yes |
CreateBeneficiaryCompanyWallet | BeneficiaryAccountNumber | Yes |
UpdateUser | UserId | Yes |
UpdateBeneficiary | BeneficiaryID | Yes |
GetEntities | UserID | Yes |
CompanyAdvancedProfile, GetCompanyAdvancedProfileDetails | BeneficiaryAccountNumber | Yes |
GetConnectedCompanyFundRequest, GetCompanyFees, TransferTaxInformation | BeneficiaryAccountNumber | Yes |
FundWalletUsingBankTransfer | BeneficiaryAccountNumber | Yes |
BookExchange | AccountNumber | Yes |
UserWithdrawFund | UserID | Yes, plus the account holder's one-time password |
BeneficiaryCompanyWithdrawFund | BeneficiaryAccountNumber | Yes, plus the account holder's one-time password |
UpdateBeneficiaryCompanyWallet | BeneficiaryAccountNumber | No: it works for a business you created, paid or are connected to |
GetUserWallets | UserID | No |
GetUserWalletTransactionsByRemitter | UserID, with your own SPN in RemitterAccountNo | No |
GetConnectedStatus | UserID | No |
GetOTPAuthorizedVendor, ValidateOTPAuthorizeVendor | RecipientUserId, RecipientUserID | No: these calls make the connection |
BatchTransfer | RecipientId, in each item | No |
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
Connect to an account that already exists, with a one-time password.
GuideBank accounts & transfersLink a bank account for a connected recipient, and start transfers out of its wallet.
Managing platformsHow managing platforms workHow connections and pseudo credentials fit together when you pay for client companies.
Managing platformsPseudo credentialsCall the API as a client company.