API reference

Bank accounts

These endpoints link a recipient's bank account to their Xtrm account so you can pay to it, and look up bank details. Link a bank account with LinkBankBeneficiary, list linked accounts with GetLinkedBankAccounts, and remove one with DeleteBankBeneficiary. You can also validate an IBAN before you link a bank, search for banks by national ID or SWIFT-BIC, and list the bank transfer types available in a country.

A personal account (PAT) can have up to 3 linked banks, and a company account more, up to a limit Xtrm sets. Linking can take more than one request, because some banks, jurisdictions and currencies need more information.

Every request on this page is a POST with a JSON body wrapped in an object named after the operation, and includes your company's IssuerAccountNumber.

POST/API/v4/Bank/LinkBankBeneficiary

Links a bank account to a recipient's Xtrm account, identified by UserID, so you can pay to it. The request has two parts: the recipient's contact details and address (BeneficiaryInformation) and the bank account details (BeneficiaryBankInformation).

Linking a bank account can take more than one request. Xtrm checks each request against what the bank's country and currency need for the type of recipient, individual or business. When a field is missing or in the wrong format, nothing is linked: the response is HTTP 400 with OperationStatus.Success set to false, and OperationStatus.Errors lists each field to add or fix as an object with an ErrorMessage, the FieldName to send (for example RoutingNumber), a FieldLabel you can show in your interface (for example Routing Number), IsRegulatoryField, and valueset, which lists the accepted values of a missing regulatory field, each with an id and a text. Send the whole request again with those fields filled in, and repeat until the response returns a BeneficiaryId: a resend can ask for more fields. A field whose IsRegulatoryField is true goes in RegulatoryFields as a Key / Value pair, with the FieldName as the Key.

Other failures, such as an invalid IBAN, an unknown routing code or a bank that's already linked, return messages as strings in OperationStatus.Errors.

On success, the response returns the BeneficiaryId that Xtrm generates for the linked bank profile, with its BankBeneficiaryStatus.

Note

A personal account (PAT) can have up to 3 linked banks, and a company account more, up to a limit Xtrm sets. Beyond that, LinkBankBeneficiary refuses the link with You can link maximum N banks.

Tip

Call ValidateIBAN before you link a bank account. Checking the IBAN first helps you avoid failed transactions and routing errors.

Body parameters

  • LinkBankBeneficiaryobjectRequired

    Wrapper object named after the operation.

    Child parameters1
    • requestobjectRequired

      The request payload.

      Child parameters3
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • UserIDstringRequired

        Xtrm account number of the recipient you link the bank account to: SPN for a business recipient or PAT for an individual recipient. The recipient must be connected to your company, or be your own company: any other account gets HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.

      • BeneficiaryobjectRequired

        The recipient and bank account details.

        Child parameters2
        • BeneficiaryDetailsobjectRequired

          Details about the recipient.

          Child parameters1
          • BeneficiaryInformationobjectRequired

            The recipient's contact details and address.

            Child parameters8
            • ContactNamestringRequired

              Name of the recipient, 1 to 100 characters. It can't contain special characters such as <, >, @, #, $ or %.

            • PhoneNumberstringRequired

              Phone number of the recipient, 1 to 15 characters, counting any spaces or dashes. Leave out a leading +: a number that starts with + is refused with Please remove country codes from mobile numbers.

            • AddressLine1stringRequired

              The recipient's street name, number and other delivery details.

            • AddressLine2stringOptional

              Additional address details, such as apartment or suite.

            • CitystringRequired

              The recipient's city, 1 to 100 characters.

            • RegionstringRequired

              The recipient's region or state, as the two-letter ISO code or the full state name.

            • PostalCodestringRequired

              The recipient's ZIP or other postal code.

            • CountryISO2stringRequired

              Two-letter ISO country code of the recipient's address.

        • BankDetailsobjectRequired

          Details about the bank account.

          Child parameters1
          • BeneficiaryBankInformationobjectRequired

            The bank account to link.

            Child parameters10
            • InstitutionNamestringRequired

              Name of the financial institution.

            • AccountTypestringOptional

              Type of the bank account. Must be BUSINESS, SAVINGS or CHECKING.

              Allowed values: BUSINESS, SAVINGS, CHECKING.

            • CurrencystringRequired

              Three-letter ISO currency code of the bank account.

            • SWIFTBICstringOptional

              SWIFT-BIC code of the bank, up to 12 characters. Required when the bank's country, currency and transfer type need it: then a request without a valid code gets SWIFTBIC back in Errors. Otherwise, when you send an IBAN as AccountNumber and leave this out, Xtrm takes the SWIFT-BIC from the IBAN.

            • AccountNumberstringRequired

              The account number at the institution.

            • RoutingNumberstringOptional

              Routing number or other national bank code of the financial institution. Required when the bank's country, currency and transfer type need it: then a request without a valid code gets RoutingNumber back in Errors. Otherwise, when you send an IBAN as AccountNumber and leave this out, Xtrm takes the routing code from the IBAN.

            • CountryISO2stringRequired

              Two-letter ISO country code of the bank's location.

            • WithdrawTypestring

              How money moves to this bank account: ACH, WIRE, LV (the same as ACH) or HV (the same as WIRE), in any case. Without it, Xtrm uses WIRE when the account's currency isn't the country's own, otherwise ACH where the country supports it, otherwise WIRE. A US bank for a US account holder in USD always uses ACH. Any other value is refused with WithdrawType is invalid. WithdrawType must be ACH, WIRE, HV or LV.

            • EntityIDintegerOptional

              For a business recipient, the ID of one of its entities to link the bank to; an ID that isn't one of the business's entities fails with <EntityID> Invalid Entity ID. Xtrm ignores it for an individual recipient, so the example leaves it out. See Entity IDs.

            • RegulatoryFieldsobject[]

              Extra compliance data as Key / Value pairs. Which regulatory fields you need depends on the bank's country and currency: send them only when a response lists a field whose IsRegulatoryField is true, with its FieldName as the Key. Sending RegulatoryFields for a bank that needs none fails with Regulatory field values are not required for this request., so the example leaves it out.

              Child parameters2
              • KeystringOptional

                Name of the regulatory field, e.g. AccountType.

              • ValuestringOptional

                Value for the regulatory field named in Key.

Response fields

  • LinkBankBeneficiaryResponseobject

    Response wrapper.

    Child parameters1
    • LinkBankBeneficiaryResultobject

      The result of the link request.

      Child parameters5
      • BeneficiaryIdstring

        Unique identity code that Xtrm generates for this linked bank profile.

      • BankBeneficiaryStatusstring

        Status of the newly linked bank profile, as the bank provider reports it, for example Pending or Approved. The success example returns Approved.

      • AccountIdentityLevelstring

        The identity level of the account in UserID: Draft, Basic, Standard or Advanced, from lowest to highest. The success example returns Advanced.

      • ACHDebitApprovalStatusstring

        Approval status for bank debit funding, which applies to banks linked with LinkACHDebitBankBeneficiary. null in the example.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Errorsarray

          Validation or execution error details if the call fails. When the bank needs more information, an array of objects, one per field to add or fix, each with ErrorMessage, FieldName, FieldLabel, IsRegulatoryField and valueset (the accepted values of a missing regulatory field, otherwise null); otherwise an array of message strings. Empty on success.

        • Successboolean

          Whether the operation succeeded (true / false).

Related: List a recipient's linked bank accounts · Delete a linked bank account · Validate an IBAN · Search banks by national ID · Search banks by SWIFT-BIC · List bank transfer types for a country · List regions for a country ID · Link a bank account for bank debit funding

#List a recipient's linked bank accounts

POST/API/v4/Bank/GetLinkedBankAccounts

Returns the bank accounts linked to a recipient, identified by RecipientUserId. Use it when you pay straight to a recipient's bank account.

Each entry in Beneficiary.BeneficiaryDetails describes one linked bank profile: its BeneficiaryId, the recipient's name, currency, country and transfer fee, and the bank details. The account number is masked in the example.

This is where you get the linked bank values that other calls ask for. To pay a linked bank account in a batch payment, send a Bank Transfer item (SendMethodId XTR94500) with the account's BeneficiaryId in Destination.BeneficiaryBankID. An individual recipient always needs this ID; a business recipient paid with Destination.WalletId can fall back to the bank linked to that wallet. DeleteBankBeneficiary takes the same ID as BeneficiaryBankID. UserWithdrawFund and BeneficiaryCompanyWithdrawFund take a value from the PaymentMethods list inside BankDetails as BankPaymentMethod.

Body parameters

  • GetLinkedBankAccountsobjectRequired

    Wrapper object named after the operation.

    Child parameters1
    • requestobjectRequired

      The request payload.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • RecipientUserIdstringRequired

        Xtrm account number of the recipient whose linked bank accounts you want: SPN for a business recipient or PAT for an individual recipient. It must be your own company or an account connected to it: any other account gets HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.

Response fields

  • GetLinkedBankAccountsResponseobject

    Response wrapper.

    Child parameters1
    • GetLinkedBankAccountsResultobject

      The result of the request.

      Child parameters2
      • Beneficiaryobject

        The recipient's linked bank accounts.

        Child parameters1
        • BeneficiaryDetailsobject[]

          One entry per linked bank profile.

          Child parameters7
          • BeneficiaryIdstring

            Unique identity code for the linked bank profile.

          • BeneficiaryNamestring

            Name of the recipient on the bank account.

          • Currencystring

            Three-letter ISO currency code.

          • Countrystring

            Name of the country, e.g. United States of America.

          • TransferFeenumber

            Fee for a transfer.

          • PaymentMethodsobject

            The accepted payment methods, e.g. {"Payment": "ACH"}.

            Child parameters1
            • Paymentstring

              Payment method, e.g. ACH.

          • BankDetailsobject

            Details about the linked bank account.

            Child parameters1
            • BeneficiaryBankInformationobject

              The linked bank account.

              Child parameters8
              • AccountNumberstring

                Bank account number. Masked in the example (XXXX8910).

              • BankNamestring

                Name of the bank.

              • BranchNamestring

                Bank branch identifier, e.g. San Francisco Main.

              • BankBeneficiaryStatusstring

                Status of the linked bank profile: Approved, Pending or Disabled. The example returns Approved.

              • ACHDebitApprovalStatusstring

                Approval status for bank debit funding, which applies to banks linked with LinkACHDebitBankBeneficiary. null in the example.

              • BankRoutingCodestring

                Routing code of the bank.

              • EntityIDinteger

                For a business recipient, the entity the bank is linked to. It's 0 for an individual recipient.

              • PaymentMethodsstring[]

                Payment methods available for this bank account, for example ["ACH"]. Pass one of these values as BankPaymentMethod when a recipient transfers money to this bank.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true / 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: Link a bank account to a recipient · Delete a linked bank account · List bank accounts linked for bank debit · Transfer from an individual recipient's wallet · Transfer from a business recipient's wallet · Create a batch payment

#Delete a linked bank account

POST/API/v4/Bank/DeleteBankBeneficiary

Deletes a bank account linked to a recipient. Pass the recipient's account number as RecipientAccountNumber and the linked bank's BeneficiaryBankID, which you get from GetLinkedBankAccounts or GetACHDebitLinkedBankAccounts.

On success, the response returns the BeneficiaryBankID of the deleted bank.

Body parameters

  • DeleteBankBeneficiaryobjectRequired

    Wrapper object named after the operation.

    Child parameters1
    • requestobjectRequired

      The request payload.

      Child parameters3
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • RecipientAccountNumberstringRequired

        Xtrm account number of the account you are deleting the linked bank for, starting with SPN for companies or PAT for personal accounts. It must be your own company or an account connected to it: any other account gets HTTP 400 with Not authorized to access this resource. Make One Time Password API Call to access this resource.

      • BeneficiaryBankIDstringRequired

        Bank-dependent ID of the linked bank to delete. Get it from GetLinkedBankAccounts or GetACHDebitLinkedBankAccounts.

Response fields

  • DeleteBankBeneficiaryobject

    Response wrapper.

    Child parameters1
    • DeleteBankBeneficiaryResultobject

      The result of the delete request.

      Child parameters2
      • BeneficiaryBankIDstring

        Bank-dependent ID of the deleted linked bank.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true / false).

        • Errorsstring[]

          Validation or execution error details if the call fails. An empty array [] when the call succeeds, so decide with Success.

Related: List a recipient's linked bank accounts · List bank accounts linked for bank debit · Link a bank account to a recipient

#Validate an IBAN

POST/API/v4/Bank/ValidateIBAN

Checks whether an International Bank Account Number (IBAN) is structurally and mathematically valid for the country in BankCountryISO2. When the IBAN is valid and the BIC can be derived, the response also returns the matching SWIFTBIC.

Call this endpoint before you link a bank account or start a payment to one. Checking the IBAN first helps you avoid failed transactions and routing errors.

Body parameters

  • ValidateIBANobjectRequired

    Wrapper object named after the operation.

    Child parameters1
    • requestobjectRequired

      The request payload.

      Child parameters3
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • IBANstringRequired

        The International Bank Account Number (IBAN) to validate.

      • BankCountryISO2stringRequired

        Two-letter ISO country code of the bank's location.

Response fields

  • ValidateIBANResponseobject

    Response wrapper.

    Child parameters1
    • ValidateIBANResultobject

      The result of the validation.

      Child parameters3
      • IsValidboolean

        Whether the IBAN is mathematically and structurally valid (true / false).

      • SWIFTBICstring

        SWIFT-BIC routing code associated with the IBAN. Returned if the IBAN is valid and the BIC can be derived.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • 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.

        • Successboolean

          Whether the API call executed successfully (true / false). This does not tell you whether the IBAN is valid; check IsValid.

Related: Link a bank account to a recipient · Search banks by SWIFT-BIC · Search banks by national ID

#Search banks by national ID

POST/API/v4/Bank/SearchBankByNationalID

Searches the banks within a country by national ID / routing code, such as a routing number or sort code.

Each result includes the NationalIdentifier, its NationalIdType (for example USBC) and the bank's BankDetails. Results are paginated with Pagination.RecordsToSkip and Pagination.RecordsToTake, and the response's PaginationTotal reports the total number of records.

Body parameters

  • SearchBankByNationalIDobjectRequired

    Wrapper object named after the operation.

    Child parameters1
    • RequestobjectRequired

      The request payload. Note the capital R.

      Child parameters4
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • BankCountryISO2stringRequired

        Two-letter ISO country code of the bank's location.

      • NationalIDstringRequired

        The national identification routing code, such as a routing number or sort code.

      • PaginationobjectRequired

        Paging controls for the search results.

        Child parameters2
        • RecordsToSkipstringRequired

          The page number of the results to return, as an integer string: "1" for the first page, "2" for the second, and so on. It isn't a record offset, and "0" is rejected. RecordsToTake sets the page size.

        • RecordsToTakestringRequired

          Maximum number of results to return per page, as an integer string, e.g. "25".

Response fields

  • SearchBankByNationalIDResponseobject

    Response wrapper.

    Child parameters1
    • SearchBankByNationalIDResultobject

      The search results.

      Child parameters3
      • Banksobject[]

        Banks that match the national ID.

        Child parameters3
        • NationalIdentifierstring

          The national identification routing code of the bank.

        • NationalIdTypestring

          Type of national routing code returned, e.g. USBC, SORT_CODE or BSB.

        • BankDetailsobject

          The bank and branch details.

          Child parameters12
          • InstitutionNamestring

            Name of the financial institution.

          • BranchInformationstring

            Additional details or the name of the specific bank branch. null in the example.

          • AddressLine1string

            First line of the bank branch's physical address.

          • AddressLine2string

            Second line of the bank branch's physical address.

          • AddressLine3string

            Third line of the bank branch's physical address.

          • AddressLine4string

            Fourth line of the bank branch's physical address.

          • Citystring

            City where the bank branch is located.

          • CountryISO2string

            Two-letter ISO country code of the bank.

          • CountryNamestring

            Name of the country where the bank branch is located.

          • PostalCodestring

            Postal or ZIP code of the bank branch.

          • BranchNamestring

            Name of the bank branch.

          • Regionstring

            Region or state of the bank branch, e.g. CALIFORNIA.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true / 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.

      • PaginationTotalobject

        Paging information for this result set.

        Child parameters3
        • RecordsTotalinteger

          Total number of records available for this query.

        • RecordsToSkipinteger

          The RecordsToSkip value from the request.

        • RecordsToTakeinteger

          Maximum number of results requested per page.

Related: Search banks by SWIFT-BIC · Validate an IBAN · Link a bank account to a recipient · List countries

#Search banks by SWIFT-BIC

POST/API/v4/Bank/SearchBankByBIC

Searches the banks within a country by SWIFT-BIC code.

Each result includes the institution name, branch name and address, and the branch's NationalId routing number. Results are paginated with Pagination.RecordsToSkip and Pagination.RecordsToTake, and the response's PaginationTotal reports the total number of records.

Body parameters

  • SearchBankByBICobjectRequired

    Wrapper object named after the operation.

    Child parameters1
    • RequestobjectRequired

      The request payload. Note the capital R.

      Child parameters4
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • BankCountryISO2stringRequired

        Two-letter ISO country code of the bank's location.

      • SWIFTBICstringRequired

        SWIFT-BIC routing code to search for.

      • PaginationobjectRequired

        Paging controls for the search results.

        Child parameters2
        • RecordsToSkipstringRequired

          The page number of the results to return, as an integer string: "1" for the first page, "2" for the second, and so on. It isn't a record offset, and "0" is rejected. RecordsToTake sets the page size.

        • RecordsToTakestringRequired

          Maximum number of results to return per page, as an integer string, e.g. "25".

Response fields

  • SearchBankbyBICResponseobject

    Response wrapper. Note the lowercase by.

    Child parameters1
    • SearchBankbyBICResultobject

      The search results.

      Child parameters3
      • Banksobject[]

        Banks that match the SWIFT-BIC.

        Child parameters15
        • InstitutionNamestring

          Name of the financial institution.

        • BICstring

          SWIFT-BIC routing code of the bank. null in the example.

        • Regionstring

          Region or state of the bank branch, e.g. NEW JERSEY.

        • NationalIdstring

          National identification routing number of the bank.

        • BranchNamestring

          Name of the bank branch.

        • BranchCodestring

          Identifier code of the bank branch. null in the example.

        • RoutingTypestring

          The routing system or network type associated with the bank.

        • AddressLine1string

          First line of the bank branch's physical address.

        • AddressLine2string

          Second line of the bank branch's physical address.

        • AddressLine3string

          Third line of the bank branch's physical address.

        • AddressLine4string

          Fourth line of the bank branch's physical address.

        • Citystring

          City where the bank branch is located.

        • CountryNamestring

          Name of the country where the bank branch is located.

        • CountryCodestring

          Two-letter ISO country code of the bank.

        • PostalCodestring

          Postal or ZIP code of the bank branch.

      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true / 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.

      • PaginationTotalobject

        Paging information for this result set.

        Child parameters3
        • RecordsTotalinteger

          Total number of records available for this query.

        • RecordsToSkipinteger

          The RecordsToSkip value from the request.

        • RecordsToTakeinteger

          Maximum number of results requested per page.

Related: Search banks by national ID · Validate an IBAN · Link a bank account to a recipient · List countries

#List bank transfer types for a country

POST/API/v4/Bank/GetBankWithdrawTypes

Returns the bank transfer types (wire, ACH and similar systems) for the country in CountryISO2. Get country codes from GetCountry.

Body parameters

  • GetBankWithdrawTypesobjectRequired

    Wrapper object named after the operation.

    Child parameters1
    • requestobjectRequired

      The request payload.

      Child parameters2
      • IssuerAccountNumberstringRequired

        Your company's Xtrm account number, starting with SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send the SPN of the company you act on behalf of.

      • CountryISO2stringRequired

        Two-letter ISO country code. Get it from GetCountry.

Response fields

  • GetBankWithdrawTypesResponseobject

    Response wrapper.

    Child parameters1
    • GetBankWithdrawTypesResultobject

      The result of the request.

      Child parameters2
      • OperationStatusobject

        Outcome of the call.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true / false).

        • Errorsstring[]

          Validation or execution error details if the call fails. null when the call succeeds, so decide with Success.

      • WithdrawTypesstring[]

        The bank transfer types, for example ACH or WIRE.

Related: List countries · Link a bank account to a recipient