Guide

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_TOKEN environment variable. Every request in this guide sends it as Authorization: Bearer <token>. See Authentication.
  • Your company account number. It starts with SPN and goes in IssuerAccountNumber on every call. With pseudo credentials, it's the SPN of the company you act on behalf of. The samples use SPN1111222.
  • The account number of the account to connect: PAT… for an individual recipient or SPN… for a business recipient. Look up a person by email with CheckUserExist, which returns AccountNo, or a business with CheckBeneficiaryExist, which returns AccountNumber. 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 the Name and Email of the match. The samples connect John Smith ([email protected]), whose personal account is PAT1111002.
  • 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.

StepCallKeep from the response
1GetConnectedStatusStatus
2GetOTPAuthorizedVendor, only if not connectedOperationStatus.Success
3ValidateOTPAuthorizeVendorOperationStatus.Success
4GetUserWalletBalance, or any other call that needs the connectionBalance

#Connect an account

  1. 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: a PAT number for an individual recipient or an SPN number for a business recipient. The request object is spelled Request on this endpoint and request on 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"
        }
      }
    }'
    Response
    {
      "GetConnectedStatusResponse": {
        "GetConnectedStatusResult": {
          "Status": "Not Connected",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Check OperationStatus.Success, then keep Status, 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 of Status:

    • Connected: skip steps 2 and 3 and go straight to step 4.
    • Not Connected: continue with step 2.
    • Pending or Cancelled: 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 Status to Connected exactly. Not Connected contains the word Connected, so a substring or "contains" check would treat an account you aren't connected to as connected. Check a connection explains each value.

  2. 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 in RecipientUserId. 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"
        }
      }
    }'
    Response
    {
      "GetOTPAuthorizedVendorResponse": {
        "GetOTPAuthorizedVendorResult": {
          "Message": "One Time Password Sent",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Check OperationStatus.Success. Message is 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 same IssuerAccountNumber and 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 409 with Already authorized vendor to access this resource.

    Not a transfer code

    This OTP connects your company to the account. It isn't the OTP that UserWithdrawFund generates on its first call and takes when you resubmit. Don't use GetOTPAuthorizedVendor to get a code for a recipient transfer. See Connection OTPs and operation OTPs.

  3. Validate the code

    When the account holder gives you the code, pass it to ValidateOTPAuthorizeVendor in OneTimePassword, with the same IssuerAccountNumber and account number you used in step 2. On this endpoint the account-number field is spelled RecipientUserID.

    OneTimePassword is 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 with 0 keeps 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"
        }
      }
    }'
    Response
    {
      "ValidateOTPAuthorizeVendorResponse": {
        "ValidateOTPAuthorizeVendorResult": {
          "Message": "Authorized",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    When OperationStatus.Success is true, the code was accepted and John's account is connected to your company. Message is a human-readable status, such as Authorized, so we recommend not matching on it. Instead, confirm the connection by calling GetConnectedStatus again, as in step 1: Status is now exactly Connected. Then save Status with 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 GetConnectedStatus again before an operation that needs the connection. See How a connection ends.

  4. Check the person's wallet balance

    Now use the connection. GetUserWalletBalance returns 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's PAT number in UserId (lowercase d on this endpoint) and the currency in Currency.

    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"
        }
      }
    }'
    Response
    {
      "UserWalletBalnceResponse": {
        "UserWalletBalanceResult": {
          "Balance": 240.75,
          "Currency": "USD",
          "OperationStatus": {
            "Success": true,
            "Errors": null
          }
        }
      }
    }

    Balance is the available balance of John's USD wallet, as a JSON number. The response wrapper is spelled UserWalletBalnceResponse, so read it exactly as returned. Before you connected, the same request failed with HTTP 400 and Not 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:

    Connections and manager services lists every call a connection unlocks. To pay John, you don't need any of this: put PAT1111002 in a batch item's RecipientId, as in Create a batch payment.

#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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Handle a rejected code calmly. If Success is false, 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.
  6. Confirm and record. Show that the connection worked, then save the Status from GetConnectedStatus. 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.

OTPHow Xtrm generates itWhere you send it backWhat it confirms
ConnectionGetOTPAuthorizedVendor sends it to the person or businessOneTimePassword in ValidateOTPAuthorizeVendorThe connection between your company and the account
Recipient transferThe first UserWithdrawFund call without OTP sends it to the personal account holderOTP when you resubmit UserWithdrawFundThat transfer
Business recipient transferThe first BeneficiaryCompanyWithdrawFund call without OTP sends it to the primary contact on the business recipient's accountOTP when you resubmit BeneficiaryCompanyWithdrawFundThat transfer
Mobile number changeThe first UpdateUser call that adds or changes the mobile number, with OTP set to "", texts it to the new numberOTP when you resubmit the same UpdateUser requestThat 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 200 only on success. A failure returns 400 for a request Xtrm rejects, 401 when IssuerAccountNumber isn't the company your credentials belong to, 409 when the account is already connected, or 500 on a temporary error. Every failure sets OperationStatus.Success to false and lists the reasons in OperationStatus.Errors, an array of messages. Log them. See Errors.
  • The code isn't accepted. ValidateOTPAuthorizeVendor returns 400 with Invalid Authorization. for a wrong code, or Activation Code Expired for 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. GetConnectedStatus uses Request and UserID, GetOTPAuthorizedVendor uses request and RecipientUserId, ValidateOTPAuthorizeVendor uses request and RecipientUserID, and GetUserWalletBalance uses request and UserId. Xtrm matches field names without regard to case, so these differences don't cause errors on their own. Copy each name as shown anyway. Send OneTimePassword as a string, and read Balance as a number.
  • A different company in IssuerAccountNumber. Send the same IssuerAccountNumber in every call. With pseudo credentials, it's the SPN of the company you act on behalf of.
  • A Status other than Connected. Pending, Cancelled and Not Connected all mean your company can't act on the account yet. Treat anything other than an exact Connected as not connected, and connect with steps 2 and 3.
  • A call that needs the connection fails. It returns 400 or 401 with an error such as Not authorized to access this resource. Make One Time Password API Call to access this resource. The account isn't connected to the company in IssuerAccountNumber, or the connection has ended. Check GetConnectedStatus and connect again with steps 2 and 3.

#Next steps

Every field of the three connection calls is in the OTP & connections reference.