Connect existing accounts
Some of the people and businesses you work with already have an Xtrm account. You can pay them straight away. When you want to do more for them, such as check their wallet balance, link a bank account or start a transfer out of their wallet, connect your company to their account first.
It takes up to three calls, and the account holder stays in control: nothing connects until they give you the one-time password (OTP) that Xtrm sends them. Then you'll put the connection to work by checking their wallet balance.
#Before you begin
- Sandbox credentials. Your client ID and secret from Settings → Integrations → Get Credentials in the sandbox web app, with your IP addresses approved. See Sandbox & environments.
- An access token in the
XTRM_ACCESS_TOKENenvironment variable. Every request in this guide sends it asAuthorization: Bearer <token>. See Authentication. - Your company account number. It starts with
SPNand goes inIssuerAccountNumberon every call. With pseudo credentials, it's theSPNof the company you act on behalf of. The samples useSPN1111222. - The account number of the account to connect:
PAT…for an individual recipient orSPN…for a business recipient. Look up a person by email withCheckUserExist, which returnsAccountNo, or a business withCheckBeneficiaryExist, which returnsAccountNumber. For a business, search by its email domain on its own when you know it, since a name search can return several companies, and check theNameandEmailof the match. The samples connect John Smith ([email protected]), whose personal account isPAT1111002. - A way to reach the account holder in your app. Xtrm sends the code to them, and they give it to you.
#When you need a connection
You don't need a connection to pay an account in a batch, and paying it doesn't connect it. You need one to manage more for the account: its wallets and wallet activity, its bank accounts and cards, its profile, and transfers out of its wallets. Connections and manager services lists what each call needs.
An account your company created with CreateUser or CreateBeneficiary is already connected. This guide is for accounts your company didn't create, such as John Smith's, which you found with CheckUserExist.
| Step | Call | Keep from the response |
|---|---|---|
| 1 | GetConnectedStatus | Status |
| 2 | GetOTPAuthorizedVendor, only if not connected | OperationStatus.Success |
| 3 | ValidateOTPAuthorizeVendor | OperationStatus.Success |
| 4 | GetUserWalletBalance, or any other call that needs the connection | Balance |
#Connect an account
- Check the connection status
This call tells you whether you need steps 2 and 3: send a connection OTP only when your company isn't connected to the account.
Put the account number in
UserID: aPATnumber for an individual recipient or anSPNnumber for a business recipient. The request object is spelledRequeston this endpoint andrequeston the other two OTP calls in this guide. Xtrm matches field names without regard to case, so a casing difference doesn't cause an error. We still recommend copying each spelling as shown.curl -X POST "https://xapisandbox.xtrm.com/API/v4/OTP/GetConnectedStatus" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetConnectedStatus": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT1111002" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/OTP/GetConnectedStatus', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetConnectedStatus: { Request: { IssuerAccountNumber: 'SPN1111222', UserID: 'PAT1111002', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/OTP/GetConnectedStatus", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetConnectedStatus": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT1111002", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetConnectedStatus": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT1111002" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/OTP/GetConnectedStatus", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetConnectedStatus": { "Request": { "IssuerAccountNumber": "SPN1111222", "UserID": "PAT1111002" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/OTP/GetConnectedStatus")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/OTP/GetConnectedStatus'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetConnectedStatus' => [ 'Request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserID' => 'PAT1111002', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetConnectedStatusResponse": { "GetConnectedStatusResult": { "Status": "Not Connected", "OperationStatus": { "Success": true, "Errors": null } } } }Check
OperationStatus.Success, then keepStatus, the connection status between your company and the account. John's account isn't connected to your company yet, so continue with step 2. For each value ofStatus:Connected: skip steps 2 and 3 and go straight to step 4.Not Connected: continue with step 2.PendingorCancelled: a connection request made in the Xtrm web app is still waiting or was cancelled. Neither connects the accounts, so continue with step 2 to connect now.
Compare
StatustoConnectedexactly.Not Connectedcontains the wordConnected, so a substring or "contains" check would treat an account you aren't connected to as connected. Check a connection explains each value. - Send the connection one-time password
When you aren't connected, call
GetOTPAuthorizedVendor. Xtrm generates a one-time password and sends it to the account holder inRecipientUserId. By giving that code to you, the account holder lets your company access their wallets and wallet activity, their bank accounts and cards, and their profile, and start transfers out of their wallets, each with its own one-time password from them. See What the account holder agrees to.We recommend making this call only after the account holder asks to connect in your app, so nobody receives a code they don't expect. See Collect the code in your app.
curl -X POST "https://xapisandbox.xtrm.com/API/v4/OTP/GetOTPAuthorizedVendor" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetOTPAuthorizedVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT1111002" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/OTP/GetOTPAuthorizedVendor', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetOTPAuthorizedVendor: { request: { IssuerAccountNumber: 'SPN1111222', RecipientUserId: 'PAT1111002', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/OTP/GetOTPAuthorizedVendor", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetOTPAuthorizedVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT1111002", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetOTPAuthorizedVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT1111002" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/OTP/GetOTPAuthorizedVendor", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetOTPAuthorizedVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserId": "PAT1111002" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/OTP/GetOTPAuthorizedVendor")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/OTP/GetOTPAuthorizedVendor'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetOTPAuthorizedVendor' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'RecipientUserId' => 'PAT1111002', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "GetOTPAuthorizedVendorResponse": { "GetOTPAuthorizedVendorResult": { "Message": "One Time Password Sent", "OperationStatus": { "Success": true, "Errors": null } } } }Check
OperationStatus.Success.Messageis a human-readable confirmation, so we recommend showing your own text in your app rather than matching on it. Nothing from this response goes into step 3: you send the sameIssuerAccountNumberand account number again, with the code.Xtrm emails the six-digit code to the account holder, and also texts it when their Xtrm account has a mobile number. For a business recipient, the code goes to the primary contact on the company's Xtrm account. The code is valid for up to 15 minutes and works once. Requesting another code replaces the previous one, so only the most recent code works.
If your company is already connected to the account, the call sends no code and returns HTTP
409withAlready authorized vendor to access this resource.Not a transfer code
This OTP connects your company to the account. It isn't the
OTPthatUserWithdrawFundgenerates on its first call and takes when you resubmit. Don't useGetOTPAuthorizedVendorto get a code for a recipient transfer. See Connection OTPs and operation OTPs. - Validate the code
When the account holder gives you the code, pass it to
ValidateOTPAuthorizeVendorinOneTimePassword, with the sameIssuerAccountNumberand account number you used in step 2. On this endpoint the account-number field is spelledRecipientUserID.OneTimePasswordis exactly six digits, sent as a string, such as"123456". Keep the code a string from your input field to the request, so a code that starts with0keeps its leading zero.curl -X POST "https://xapisandbox.xtrm.com/API/v4/OTP/ValidateOTPAuthorizeVendor" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "ValidateOTPAuthorizeVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserID": "PAT1111002", "OneTimePassword": "123456" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/OTP/ValidateOTPAuthorizeVendor', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ ValidateOTPAuthorizeVendor: { request: { IssuerAccountNumber: 'SPN1111222', RecipientUserID: 'PAT1111002', OneTimePassword: '123456', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/OTP/ValidateOTPAuthorizeVendor", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "ValidateOTPAuthorizeVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserID": "PAT1111002", "OneTimePassword": "123456", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "ValidateOTPAuthorizeVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserID": "PAT1111002", "OneTimePassword": "123456" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/OTP/ValidateOTPAuthorizeVendor", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "ValidateOTPAuthorizeVendor": { "request": { "IssuerAccountNumber": "SPN1111222", "RecipientUserID": "PAT1111002", "OneTimePassword": "123456" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/OTP/ValidateOTPAuthorizeVendor")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/OTP/ValidateOTPAuthorizeVendor'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'ValidateOTPAuthorizeVendor' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'RecipientUserID' => 'PAT1111002', 'OneTimePassword' => '123456', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "ValidateOTPAuthorizeVendorResponse": { "ValidateOTPAuthorizeVendorResult": { "Message": "Authorized", "OperationStatus": { "Success": true, "Errors": null } } } }When
OperationStatus.Successistrue, the code was accepted and John's account is connected to your company.Messageis a human-readable status, such asAuthorized, so we recommend not matching on it. Instead, confirm the connection by callingGetConnectedStatusagain, as in step 1:Statusis now exactlyConnected. Then saveStatuswith the account number and the time you checked, so your app knows which accounts it's connected to. Don't store the code itself.A connection doesn't expire. It lasts until it's disconnected in the Xtrm web app, which ends your company's access at once, so check
GetConnectedStatusagain before an operation that needs the connection. See How a connection ends. - Check the person's wallet balance
Now use the connection.
GetUserWalletBalancereturns the balance of a person's wallet in one currency, and it works only for an account that's connected to your company. Send John'sPATnumber inUserId(lowercasedon this endpoint) and the currency inCurrency.curl -X POST "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance" \ -H "Authorization: Bearer $XTRM_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT1111002", "Currency": "USD" } } }'const response = await fetch('https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance', { method: 'POST', headers: { Authorization: `Bearer ${process.env.XTRM_ACCESS_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ GetUserWalletBalance: { request: { IssuerAccountNumber: 'SPN1111222', UserId: 'PAT1111002', Currency: 'USD', }, }, }), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2));import os import requests response = requests.post( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance", headers={"Authorization": f"Bearer {os.environ['XTRM_ACCESS_TOKEN']}"}, json={ "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT1111002", "Currency": "USD", }, }, }, ) response.raise_for_status() print(response.json())using System.Net.Http.Headers; using System.Text; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("XTRM_ACCESS_TOKEN")); var json = """ { "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT1111002", "Currency": "USD" } } } """; var response = await client.PostAsync( "https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance", new StringContent(json, Encoding.UTF8, "application/json")); response.EnsureSuccessStatusCode(); Console.WriteLine(await response.Content.ReadAsStringAsync());import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; String json = """ { "GetUserWalletBalance": { "request": { "IssuerAccountNumber": "SPN1111222", "UserId": "PAT1111002", "Currency": "USD" } } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance")) .header("Authorization", "Bearer " + System.getenv("XTRM_ACCESS_TOKEN")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());<?php $ch = curl_init('https://xapisandbox.xtrm.com/API/v4/Wallet/GetUserWalletBalance'); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode([ 'GetUserWalletBalance' => [ 'request' => [ 'IssuerAccountNumber' => 'SPN1111222', 'UserId' => 'PAT1111002', 'Currency' => 'USD', ], ], ]), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('XTRM_ACCESS_TOKEN'), 'Content-Type: application/json', ], ]); $response = curl_exec($ch); print_r(json_decode($response, true));Response{ "UserWalletBalnceResponse": { "UserWalletBalanceResult": { "Balance": 240.75, "Currency": "USD", "OperationStatus": { "Success": true, "Errors": null } } } }Balanceis the available balance of John's USD wallet, as a JSON number. The response wrapper is spelledUserWalletBalnceResponse, so read it exactly as returned. Before you connected, the same request failed with HTTP400andNot authorized to access this resource. Make One Time Password API Call to access this resource.With the connection in place, your company can do more for John:
- Link a bank account for him with
LinkBankBeneficiary, or list the ones he has withGetLinkedBankAccounts. Bank accounts & transfers walks through linking a bank and paying it. - Start a transfer out of his wallet with
UserWithdrawFund. Each transfer needs its own one-time password from John. See Transfer from a recipient's wallet. - Update his profile with
UpdateUser.
Connections and manager services lists every call a connection unlocks. To pay John, you don't need any of this: put
PAT1111002in a batch item'sRecipientId, as in Create a batch payment. - Link a bank account for him with
#Collect the code in your app
Most of the work in the connection flow is in the screens around the API calls. These steps are our recommendation, not something the API requires:
- Explain, then ask. Before you send a code, tell the account holder which company is asking to connect and what connecting allows: access to their wallets and wallet activity, their bank accounts and cards, and their profile, plus transfers out of their wallets that each need a one-time password from them. What the account holder agrees to has wording you can use. Send the code only when they choose Connect or Send code.
- Show the entry screen straight away. After step 2 succeeds, tell them a six-digit code is on its way to the email address on their Xtrm account, and by text message too if the account has a mobile number.
- Make the code easy to enter. Use one numeric field (
inputmode="numeric",autocomplete="one-time-code"), strip spaces and dashes, and enable submit only when the field holds exactly six digits. - Validate on your server. Your browser or mobile app posts the code to your backend, and your backend calls
ValidateOTPAuthorizeVendor. Your access token never leaves your server. - Handle a rejected code calmly. If
Successisfalse, say the code wasn't accepted and offer to try again or send a new code. Limit attempts and add a short wait before a resend on your side. A code is valid for up to 15 minutes, and a new code replaces the old one, so ask the account holder to enter the code from the most recent message. - Confirm and record. Show that the connection worked, then save the
StatusfromGetConnectedStatus. Never log or store the code.
Label this screen as a connection, for example "Connect your Xtrm account to" followed by your company's name. An account holder can receive several kinds of Xtrm codes, and a clear label helps them enter the right one.
#Connection OTPs and operation OTPs
The API uses two kinds of one-time password. The connection OTP in this guide connects your company to an account. Some operations use an OTP of their own that confirms a single request. They're different codes, so don't use one in place of the other.
| OTP | How Xtrm generates it | Where you send it back | What it confirms |
|---|---|---|---|
| Connection | GetOTPAuthorizedVendor sends it to the person or business | OneTimePassword in ValidateOTPAuthorizeVendor | The connection between your company and the account |
| Recipient transfer | The first UserWithdrawFund call without OTP sends it to the personal account holder | OTP when you resubmit UserWithdrawFund | That transfer |
| Business recipient transfer | The first BeneficiaryCompanyWithdrawFund call without OTP sends it to the primary contact on the business recipient's account | OTP when you resubmit BeneficiaryCompanyWithdrawFund | That transfer |
| Mobile number change | The first UpdateUser call that adds or changes the mobile number, with OTP set to "", texts it to the new number | OTP when you resubmit the same UpdateUser request | That update |
An operation OTP expires 10 minutes after Xtrm sends it, sooner than a connection OTP. If you resubmit with a wrong or expired code, the call fails, Xtrm sends the account holder a new code, and you resubmit the same request with that one.
UpdateUser can need both kinds: your company must be connected to the individual recipient, and adding or changing the mobile number also needs that update's own OTP, whether or not the profile already has a number. For recipient transfers, see Bank accounts & transfers.
#What can go wrong
- A failed OTP call returns an error status. The three OTP endpoints return HTTP
200only on success. A failure returns400for a request Xtrm rejects,401whenIssuerAccountNumberisn't the company your credentials belong to,409when the account is already connected, or500on a temporary error. Every failure setsOperationStatus.Successtofalseand lists the reasons inOperationStatus.Errors, an array of messages. Log them. See Errors. - The code isn't accepted.
ValidateOTPAuthorizeVendorreturns400withInvalid Authorization.for a wrong code, orActivation Code Expiredfor a code that has expired. An earlier code stops working as soon as you request a new one. Treat any failure as "not connected yet" and let the account holder try again or ask for a new code. - The wrong kind of code. The connection code and the code for a recipient transfer are different codes, and an account holder can receive both. See Connection OTPs and operation OTPs.
- Field names and types differ between calls.
GetConnectedStatususesRequestandUserID,GetOTPAuthorizedVendorusesrequestandRecipientUserId,ValidateOTPAuthorizeVendorusesrequestandRecipientUserID, andGetUserWalletBalanceusesrequestandUserId. Xtrm matches field names without regard to case, so these differences don't cause errors on their own. Copy each name as shown anyway. SendOneTimePasswordas a string, and readBalanceas a number. - A different company in
IssuerAccountNumber. Send the sameIssuerAccountNumberin every call. With pseudo credentials, it's theSPNof the company you act on behalf of. - A
Statusother thanConnected.Pending,CancelledandNot Connectedall mean your company can't act on the account yet. Treat anything other than an exactConnectedas not connected, and connect with steps 2 and 3. - A call that needs the connection fails. It returns
400or401with an error such asNot authorized to access this resource. Make One Time Password API Call to access this resource. The account isn't connected to the company inIssuerAccountNumber, or the connection has ended. CheckGetConnectedStatusand connect again with steps 2 and 3.
#Next steps
What your company can do before and after it connects, in the API and the web app.
Bank accounts & transfersLink a bank account for a connected recipient, and start transfers out of its wallet with an operation OTP.
Create a batch paymentPay many recipients in one batch, connected or not, and track each payment.
Complete the advanced profileUpload a company's documents in the web app and submit its KYB (know your business) application, for your company or a connected company.
Every field of the three connection calls is in the OTP & connections reference.