API reference

OTP & connections

Use these endpoints to check whether your company is connected to a personal (PAT) or company (SPN) account, and to connect to an existing account with a one-time password (OTP) that its holder gives you. Connecting gives your company access to the account's wallets and wallet activity, its bank accounts and cards, and its profile. Your company can also start transfers out of its wallets, and each transfer needs a one-time password from the account holder. You don't need a connection to pay the account. See Connections and manager services. An account your company creates with CreateUser or CreateBeneficiary is connected from the start. The operation names call your company the vendor.

Call GetConnectedStatus to check the connection. If the accounts aren't connected, call GetOTPAuthorizedVendor to send an OTP to the account holder, then pass the six-digit OTP they receive to ValidateOTPAuthorizeVendor to complete the connection.

Each request identifies your company in IssuerAccountNumber: the SPN account number tied to your API credentials or, with pseudo credentials, the SPN of the company you act on behalf of. The connection OTP isn't the OTP for a recipient transfer: UserWithdrawFund generates its own OTP on the first call, which expires after 10 minutes, and takes it in an OTP field when you resubmit.

#Get the connection status of an account

POST/API/v4/OTP/GetConnectedStatus

Returns the connection status between your company and the personal or company account in UserID. The status is returned in Status: Connected, Pending, Cancelled, or Not Connected. Only Connected lets your company act on the account. Pending is a connection request made in the Xtrm web app that hasn't been accepted yet, and Cancelled is a request that was cancelled. A declined request, or a connection that has been disconnected, reads Not Connected. A Pending connection doesn't let your company do anything a Not Connected one can't: to connect without waiting, use a one-time password.

If they aren't connected, use GetOTPAuthorizedVendor to send a one-time password (OTP) to the account holder, so they can connect and authorize your company. Then call ValidateOTPAuthorizeVendor to validate the OTP and complete the connection.

Body parameters

  • GetConnectedStatusobjectRequired

    Operation wrapper.

    Child parameters1
    • RequestobjectRequired

      The request object. Note the capital R in this endpoint's wrapper.

      Child parameters2
      • IssuerAccountNumberstringRequired

        The unique Xtrm account identifier, starting with SPN, for the company account associated with the credentials you use for the API call. If you use pseudo credentials, this is the SPN of the company on whose behalf you make the call.

      • UserIDstringRequired

        The unique Xtrm account identifier of the account you query, starting with SPN for company accounts or PAT for personal accounts.

Response fields

  • GetConnectedStatusResponseobject

    Response wrapper.

    Child parameters1
    • GetConnectedStatusResultobject

      The result of the operation.

      Child parameters2
      • Statusstring

        The current connection status between your company and the account: Connected, Pending (a connection request made in the Xtrm web app that hasn't been accepted yet), Cancelled, or Not Connected. Only Connected lets your company act on the account.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Send a connection one-time password · Validate a connection one-time password · Check whether an individual recipient exists · Search for existing company accounts · Update an individual recipient · Get advanced profile details

#Send a connection one-time password

POST/API/v4/OTP/GetOTPAuthorizedVendor

Generates a one-time password (OTP) for the account in RecipientUserId, a personal (PAT) or company (SPN) account. By giving you the OTP, the account holder connects their account to your company (the vendor in the operation name). Connecting gives your company access to the account's wallets and wallet activity, its bank accounts and cards, and its profile. Your company can also start transfers out of its wallets, and each transfer needs a one-time password from the account holder. You don't need a connection to pay the account. See Connections and manager services. On success, Message confirms that the OTP was sent, for example One Time Password Sent.

Xtrm emails the six-digit OTP to the account holder, and also texts it when the account has a mobile number. For a company account, it goes to the primary contact on the account. The OTP is valid for up to 15 minutes and works once, and requesting a new one replaces the previous one. If your company is already connected to the account, the call sends no OTP and returns HTTP 409 with Already authorized vendor to access this resource.

Use it when GetConnectedStatus shows that your company isn't connected to the account. To complete the connection, pass the OTP the account holder received to ValidateOTPAuthorizeVendor.

Note

This OTP connects your company to the account. It isn't the OTP for a recipient transfer, which UserWithdrawFund generates on its first call and takes when you resubmit.

Body parameters

  • GetOTPAuthorizedVendorobjectRequired

    Operation wrapper.

    Child parameters1
    • requestobjectRequired

      The request object.

      Child parameters2
      • IssuerAccountNumberstringRequired

        The unique Xtrm account identifier, starting with SPN, for the company account associated with the credentials you use for the API call. If you use pseudo credentials, this is the SPN of the company on whose behalf you make the call.

      • RecipientUserIdstringRequired

        The unique Xtrm account identifier of the account holder who receives the OTP, starting with SPN for company accounts or PAT for personal accounts.

Response fields

  • GetOTPAuthorizedVendorResponseobject

    Response wrapper.

    Child parameters1
    • GetOTPAuthorizedVendorResultobject

      The result of the operation.

      Child parameters2
      • Messagestring

        A human-readable confirmation that the OTP was sent, e.g. One Time Password Sent.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Get the connection status of an account · Validate a connection one-time password · List an individual recipient's wallets · List an individual recipient's wallet transactions · Transfer from an individual recipient's wallet

#Validate a connection one-time password

POST/API/v4/OTP/ValidateOTPAuthorizeVendor

Validates the one-time password (OTP) that GetOTPAuthorizedVendor sent to the account holder in RecipientUserID, and completes the connection. Called with your own credentials, it also adds the account to your company's list of recipients. If you call it with a client company's pseudo credentials, a company account is connected to the client company and to your platform, and a personal account to the client company only. For what the connection lets your company do, see Connections and manager services. On success, Message gives the status of the validation, for example Authorized. A wrong OTP returns HTTP 400 with Invalid Authorization., an expired one returns 400 with Activation Code Expired, and an account that is already connected returns 409.

Use it together with GetOTPAuthorizedVendor: send the OTP first, then submit the six-digit code the account holder received in OneTimePassword.

Body parameters

  • ValidateOTPAuthorizeVendorobjectRequired

    Operation wrapper.

    Child parameters1
    • requestobjectRequired

      The request object.

      Child parameters3
      • IssuerAccountNumberstringRequired

        The unique Xtrm account identifier, starting with SPN, for the company account associated with the credentials you use for the API call. If you use pseudo credentials, this is the SPN of the company on whose behalf you make the call.

      • RecipientUserIDstringRequired

        The unique Xtrm account identifier of the account holder whose OTP you validate, starting with SPN for company accounts or PAT for personal accounts.

      • OneTimePasswordstringRequired

        The one-time password, exactly six digits, as a string, e.g. "123456".

Response fields

  • ValidateOTPAuthorizeVendorResponseobject

    Response wrapper.

    Child parameters1
    • ValidateOTPAuthorizeVendorResultobject

      The result of the operation.

      Child parameters2
      • Messagestring

        A human-readable status of the OTP validation, for example Authorized.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

Related: Send a connection one-time password · Get the connection status of an account · List an individual recipient's wallets · List an individual recipient's wallet transactions · Transfer from an individual recipient's wallet