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/LinkBankBeneficiaryLink a bank account to a recipient - POST
/API/v4/Bank/GetLinkedBankAccountsList a recipient's linked bank accounts - POST
/API/v4/Bank/DeleteBankBeneficiaryDelete a linked bank account - POST
/API/v4/Bank/ValidateIBANValidate an IBAN - POST
/API/v4/Bank/SearchBankByNationalIDSearch banks by national ID - POST
/API/v4/Bank/SearchBankByBICSearch banks by SWIFT-BIC - POST
/API/v4/Bank/GetBankWithdrawTypesList bank transfer types for a country
#Link a bank account to a recipient
/API/v4/Bank/LinkBankBeneficiaryLinks 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.
Important
When the bank needs more information, the response is HTTP 400 with OperationStatus.Success set to false. Read Errors for the fields to add or fix, send the whole request again with them, and repeat until the response returns a BeneficiaryId.
Body parameters
LinkBankBeneficiaryobjectRequiredWrapper object named after the operation.
Child parameters1
requestobjectRequiredThe request payload.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.UserIDstringRequiredXtrm account number of the recipient you link the bank account to:
SPNfor a business recipient orPATfor an individual recipient. The recipient must be connected to your company, or be your own company: any other account gets HTTP400withNot authorized to access this resource. Make One Time Password API Call to access this resource.BeneficiaryobjectRequiredThe recipient and bank account details.
Child parameters2
BeneficiaryDetailsobjectRequiredDetails about the recipient.
Child parameters1
BeneficiaryInformationobjectRequiredThe recipient's contact details and address.
Child parameters8
ContactNamestringRequiredName of the recipient, 1 to 100 characters. It can't contain special characters such as
<,>,@,#,$or%.PhoneNumberstringRequiredPhone number of the recipient, 1 to 15 characters, counting any spaces or dashes. Leave out a leading
+: a number that starts with+is refused withPlease remove country codes from mobile numbers.AddressLine1stringRequiredThe recipient's street name, number and other delivery details.
AddressLine2stringOptionalAdditional address details, such as apartment or suite.
CitystringRequiredThe recipient's city, 1 to 100 characters.
RegionstringRequiredThe recipient's region or state, as the two-letter ISO code or the full state name.
PostalCodestringRequiredThe recipient's ZIP or other postal code.
CountryISO2stringRequiredTwo-letter ISO country code of the recipient's address.
BankDetailsobjectRequiredDetails about the bank account.
Child parameters1
BeneficiaryBankInformationobjectRequiredThe bank account to link.
Child parameters10
InstitutionNamestringRequiredName of the financial institution.
AccountTypestringOptionalType of the bank account. Must be
BUSINESS,SAVINGSorCHECKING.Allowed values:
BUSINESS,SAVINGS,CHECKING.CurrencystringRequiredThree-letter ISO currency code of the bank account.
SWIFTBICstringOptionalSWIFT-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
SWIFTBICback inErrors. Otherwise, when you send an IBAN asAccountNumberand leave this out, Xtrm takes the SWIFT-BIC from the IBAN.AccountNumberstringRequiredThe account number at the institution.
RoutingNumberstringOptionalRouting 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
RoutingNumberback inErrors. Otherwise, when you send an IBAN asAccountNumberand leave this out, Xtrm takes the routing code from the IBAN.CountryISO2stringRequiredTwo-letter ISO country code of the bank's location.
WithdrawTypestringHow money moves to this bank account:
ACH,WIRE,LV(the same asACH) orHV(the same asWIRE), in any case. Without it, Xtrm usesWIREwhen the account's currency isn't the country's own, otherwiseACHwhere the country supports it, otherwiseWIRE. A US bank for a US account holder inUSDalways usesACH. Any other value is refused withWithdrawType is invalid. WithdrawType must be ACH, WIRE, HV or LV.EntityIDintegerOptionalFor 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/Valuepairs. Which regulatory fields you need depends on the bank's country and currency: send them only when a response lists a field whoseIsRegulatoryFieldistrue, with itsFieldNameas theKey. SendingRegulatoryFieldsfor a bank that needs none fails withRegulatory field values are not required for this request., so the example leaves it out.Child parameters2
KeystringOptionalName of the regulatory field, e.g.
AccountType.ValuestringOptionalValue for the regulatory field named in
Key.
Response fields
LinkBankBeneficiaryResponseobjectResponse wrapper.
Child parameters1
LinkBankBeneficiaryResultobjectThe result of the link request.
Child parameters5
BeneficiaryIdstringUnique identity code that Xtrm generates for this linked bank profile.
BankBeneficiaryStatusstringStatus of the newly linked bank profile, as the bank provider reports it, for example
PendingorApproved. The success example returnsApproved.AccountIdentityLevelstringThe identity level of the account in
UserID:Draft,Basic,StandardorAdvanced, from lowest to highest. The success example returnsAdvanced.ACHDebitApprovalStatusstringApproval status for bank debit funding, which applies to banks linked with
LinkACHDebitBankBeneficiary.nullin the example.OperationStatusobjectOutcome of the call.
Child parameters2
ErrorsarrayValidation 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,IsRegulatoryFieldandvalueset(the accepted values of a missing regulatory field, otherwisenull); otherwise an array of message strings. Empty on success.SuccessbooleanWhether 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
/API/v4/Bank/GetLinkedBankAccountsReturns 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
GetLinkedBankAccountsobjectRequiredWrapper object named after the operation.
Child parameters1
requestobjectRequiredThe request payload.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.RecipientUserIdstringRequiredXtrm account number of the recipient whose linked bank accounts you want:
SPNfor a business recipient orPATfor an individual recipient. It must be your own company or an account connected to it: any other account gets HTTP400withNot authorized to access this resource. Make One Time Password API Call to access this resource.
Response fields
GetLinkedBankAccountsResponseobjectResponse wrapper.
Child parameters1
GetLinkedBankAccountsResultobjectThe result of the request.
Child parameters2
BeneficiaryobjectThe recipient's linked bank accounts.
Child parameters1
BeneficiaryDetailsobject[]One entry per linked bank profile.
Child parameters7
BeneficiaryIdstringUnique identity code for the linked bank profile.
BeneficiaryNamestringName of the recipient on the bank account.
CurrencystringThree-letter ISO currency code.
CountrystringName of the country, e.g.
United States of America.TransferFeenumberFee for a transfer.
PaymentMethodsobjectThe accepted payment methods, e.g.
{"Payment": "ACH"}.Child parameters1
PaymentstringPayment method, e.g.
ACH.
BankDetailsobjectDetails about the linked bank account.
Child parameters1
BeneficiaryBankInformationobjectThe linked bank account.
Child parameters8
AccountNumberstringBank account number. Masked in the example (
XXXX8910).BankNamestringName of the bank.
BranchNamestringBank branch identifier, e.g.
San Francisco Main.BankBeneficiaryStatusstringStatus of the linked bank profile:
Approved,PendingorDisabled. The example returnsApproved.ACHDebitApprovalStatusstringApproval status for bank debit funding, which applies to banks linked with
LinkACHDebitBankBeneficiary.nullin the example.BankRoutingCodestringRouting code of the bank.
EntityIDintegerFor a business recipient, the entity the bank is linked to. It's
0for an individual recipient.PaymentMethodsstring[]Payment methods available for this bank account, for example
["ACH"]. Pass one of these values asBankPaymentMethodwhen a recipient transfers money to this bank.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true/false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
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
/API/v4/Bank/DeleteBankBeneficiaryDeletes 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
DeleteBankBeneficiaryobjectRequiredWrapper object named after the operation.
Child parameters1
requestobjectRequiredThe request payload.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.RecipientAccountNumberstringRequiredXtrm account number of the account you are deleting the linked bank for, starting with
SPNfor companies orPATfor personal accounts. It must be your own company or an account connected to it: any other account gets HTTP400withNot authorized to access this resource. Make One Time Password API Call to access this resource.BeneficiaryBankIDstringRequiredBank-dependent ID of the linked bank to delete. Get it from
GetLinkedBankAccountsorGetACHDebitLinkedBankAccounts.
Response fields
DeleteBankBeneficiaryobjectResponse wrapper.
Child parameters1
DeleteBankBeneficiaryResultobjectThe result of the delete request.
Child parameters2
BeneficiaryBankIDstringBank-dependent ID of the deleted linked bank.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true/false).Errorsstring[]Validation or execution error details if the call fails. An empty array
[]when the call succeeds, so decide withSuccess.
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
/API/v4/Bank/ValidateIBANChecks 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.
Important
Success: true only means the call ran without server errors. To know whether the IBAN is valid, check IsValid.
Body parameters
ValidateIBANobjectRequiredWrapper object named after the operation.
Child parameters1
requestobjectRequiredThe request payload.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.IBANstringRequiredThe International Bank Account Number (IBAN) to validate.
BankCountryISO2stringRequiredTwo-letter ISO country code of the bank's location.
Response fields
ValidateIBANResponseobjectResponse wrapper.
Child parameters1
ValidateIBANResultobjectThe result of the validation.
Child parameters3
IsValidbooleanWhether the IBAN is mathematically and structurally valid (
true/false).SWIFTBICstringSWIFT-BIC routing code associated with the IBAN. Returned if the IBAN is valid and the BIC can be derived.
OperationStatusobjectOutcome of the call.
Child parameters2
Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.SuccessbooleanWhether the API call executed successfully (
true/false). This does not tell you whether the IBAN is valid; checkIsValid.
Related: Link a bank account to a recipient · Search banks by SWIFT-BIC · Search banks by national ID
#Search banks by national ID
/API/v4/Bank/SearchBankByNationalIDSearches 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
SearchBankByNationalIDobjectRequiredWrapper object named after the operation.
Child parameters1
RequestobjectRequiredThe request payload. Note the capital
R.Child parameters4
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.BankCountryISO2stringRequiredTwo-letter ISO country code of the bank's location.
NationalIDstringRequiredThe national identification routing code, such as a routing number or sort code.
PaginationobjectRequiredPaging controls for the search results.
Child parameters2
RecordsToSkipstringRequiredThe 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.RecordsToTakesets the page size.RecordsToTakestringRequiredMaximum number of results to return per page, as an integer string, e.g.
"25".
Response fields
SearchBankByNationalIDResponseobjectResponse wrapper.
Child parameters1
SearchBankByNationalIDResultobjectThe search results.
Child parameters3
Banksobject[]Banks that match the national ID.
Child parameters3
NationalIdentifierstringThe national identification routing code of the bank.
NationalIdTypestringType of national routing code returned, e.g.
USBC,SORT_CODEorBSB.BankDetailsobjectThe bank and branch details.
Child parameters12
InstitutionNamestringName of the financial institution.
BranchInformationstringAdditional details or the name of the specific bank branch.
nullin the example.AddressLine1stringFirst line of the bank branch's physical address.
AddressLine2stringSecond line of the bank branch's physical address.
AddressLine3stringThird line of the bank branch's physical address.
AddressLine4stringFourth line of the bank branch's physical address.
CitystringCity where the bank branch is located.
CountryISO2stringTwo-letter ISO country code of the bank.
CountryNamestringName of the country where the bank branch is located.
PostalCodestringPostal or ZIP code of the bank branch.
BranchNamestringName of the bank branch.
RegionstringRegion or state of the bank branch, e.g.
CALIFORNIA.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true/false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
PaginationTotalobjectPaging information for this result set.
Child parameters3
RecordsTotalintegerTotal number of records available for this query.
RecordsToSkipintegerThe
RecordsToSkipvalue from the request.RecordsToTakeintegerMaximum 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
/API/v4/Bank/SearchBankByBICSearches 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
SearchBankByBICobjectRequiredWrapper object named after the operation.
Child parameters1
RequestobjectRequiredThe request payload. Note the capital
R.Child parameters4
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.BankCountryISO2stringRequiredTwo-letter ISO country code of the bank's location.
SWIFTBICstringRequiredSWIFT-BIC routing code to search for.
PaginationobjectRequiredPaging controls for the search results.
Child parameters2
RecordsToSkipstringRequiredThe 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.RecordsToTakesets the page size.RecordsToTakestringRequiredMaximum number of results to return per page, as an integer string, e.g.
"25".
Response fields
SearchBankbyBICResponseobjectResponse wrapper. Note the lowercase
by.Child parameters1
SearchBankbyBICResultobjectThe search results.
Child parameters3
Banksobject[]Banks that match the SWIFT-BIC.
Child parameters15
InstitutionNamestringName of the financial institution.
BICstringSWIFT-BIC routing code of the bank.
nullin the example.RegionstringRegion or state of the bank branch, e.g.
NEW JERSEY.NationalIdstringNational identification routing number of the bank.
BranchNamestringName of the bank branch.
BranchCodestringIdentifier code of the bank branch.
nullin the example.RoutingTypestringThe routing system or network type associated with the bank.
AddressLine1stringFirst line of the bank branch's physical address.
AddressLine2stringSecond line of the bank branch's physical address.
AddressLine3stringThird line of the bank branch's physical address.
AddressLine4stringFourth line of the bank branch's physical address.
CitystringCity where the bank branch is located.
CountryNamestringName of the country where the bank branch is located.
CountryCodestringTwo-letter ISO country code of the bank.
PostalCodestringPostal or ZIP code of the bank branch.
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true/false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
PaginationTotalobjectPaging information for this result set.
Child parameters3
RecordsTotalintegerTotal number of records available for this query.
RecordsToSkipintegerThe
RecordsToSkipvalue from the request.RecordsToTakeintegerMaximum 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
/API/v4/Bank/GetBankWithdrawTypesReturns the bank transfer types (wire, ACH and similar systems) for the country in CountryISO2. Get country codes from GetCountry.
Body parameters
GetBankWithdrawTypesobjectRequiredWrapper object named after the operation.
Child parameters1
requestobjectRequiredThe request payload.
Child parameters2
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN: the account that owns the API credentials you call with. If you use pseudo credentials, send theSPNof the company you act on behalf of.CountryISO2stringRequiredTwo-letter ISO country code. Get it from
GetCountry.
Response fields
GetBankWithdrawTypesResponseobjectResponse wrapper.
Child parameters1
GetBankWithdrawTypesResultobjectThe result of the request.
Child parameters2
OperationStatusobjectOutcome of the call.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true/false).Errorsstring[]Validation or execution error details if the call fails.
nullwhen the call succeeds, so decide withSuccess.
WithdrawTypesstring[]The bank transfer types, for example
ACHorWIRE.
Related: List countries · Link a bank account to a recipient