Bank debit (ACH)
Bank debit funds your company's wallets by debiting a bank account linked to your Xtrm account, over ACH or a similar bank transfer system. Release 4.91.6 renamed ACH debit to bank debit; the operation names still use ACHDebit.
Link the bank account for approval with LinkACHDebitBankBeneficiary. To confirm that Xtrm is connected to the right account, send two micro-deposits with ReleaseACHDebitMicrodeposit and verify their amounts with VerifyACHDebitMicrodeposit. GetACHDebitLinkedBankAccounts returns each link's ACHDebitApprovalStatus. Once a bank is approved, you can fund a company wallet from it with FundWalletUsingACHDebit.
A bank debit can take 3 to 5 business days to fund the wallet. To remove a linked bank, call DeleteBankBeneficiary with the ID returned by GetACHDebitLinkedBankAccounts.
- POST
/API/v4/Bank/LinkACHDebitBankBeneficiaryLink a bank account for bank debit funding - POST
/API/v4/Bank/ReleaseACHDebitMicrodepositSend micro-deposits to a linked bank - POST
/API/v4/Bank/VerifyACHDebitMicrodepositVerify micro-deposit amounts - POST
/API/v4/Bank/GetACHDebitLinkedBankAccountsList bank accounts linked for bank debit
#Link a bank account for bank debit funding
/API/v4/Bank/LinkACHDebitBankBeneficiaryLinks a bank account for bank debit so you can use it to fund a company wallet. You send two groups of information: the account holder's name, phone number and address in Beneficiary.BeneficiaryDetails.BeneficiaryInformation, and the bank account in Beneficiary.BankDetails.BeneficiaryBankInformation.
Linking a bank can take more than one request. Xtrm checks each request against what a bank debit needs for the bank's country and currency. 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 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) and IsRegulatoryField. Send the whole request again with those fields filled in, and repeat until the response returns a BeneficiaryId. A field whose IsRegulatoryField is true goes in RegulatoryFields, as a Key/Value pair with the FieldName as the Key. Other failures, such as a bank that's already linked, return messages as strings in Errors.
The bank is linked for approval. Once it's approved for bank debit, you can use it to fund your company wallet. The response returns the link's ACHDebitApprovalStatus, and you can check it again later with GetACHDebitLinkedBankAccounts.
Important
A request that needs more information returns HTTP 400 with Success set to false and the fields to add or fix in Errors. Send the whole request again with them until the response returns a BeneficiaryId, and check OperationStatus.Success on every response.
Note
Bank-debit banks don't count toward the linked-bank limit: up to 3 banks for a personal account, and more for a company account, up to a limit Xtrm sets. But once an account has reached that limit with banks linked to receive payments, this call refuses a new bank-debit link with You can link maximum N banks.
Note
Release 4.91.6 added support for linking banks for bank debit in USD, CAD, AUD, GBP and EUR.
Body parameters
LinkACHDebitBankBeneficiaryobjectRequiredRequest wrapper, named after the operation.
Child parameters1
requestobjectRequiredThe request fields.
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.UserIDstringRequiredThe Xtrm account the bank is linked to, starting with
SPNfor a company account orPATfor a personal account: your own company, or an account connected to it. To fund your own wallets, send your ownSPN:FundWalletUsingACHDebitdebits only a bank linked to the company in itsIssuerAccountNumber. Any other account gets HTTP400withNot authorized to access this resource. Make One Time Password API Call to access this resource.BeneficiaryobjectRequiredThe account holder and the bank account to link.
Child parameters2
BeneficiaryDetailsobjectRequiredDetails about the account holder.
Child parameters1
BeneficiaryInformationobjectRequiredThe account holder's name, phone number and address.
Child parameters8
ContactNamestringRequiredThe account holder's name, 1 to 100 characters. It can't contain special characters such as
<,>,@,#,$or%.PhoneNumberstringRequiredThe account holder's phone number, as a string of 1 to 15 characters. Spaces, dashes and other formatting characters count toward the 15.
AddressLine1stringRequiredThe account holder's street name, number and other delivery details.
AddressLine2stringOptionalAdditional address details for the account holder, such as apartment or suite.
CitystringRequiredThe account holder's city, 1 to 100 characters.
RegionstringRequiredThe account holder's region or state, as either the two-letter ISO2 code or the full state name.
PostalCodestringRequiredZIP code or other postal code for the account holder.
CountryISO2stringRequiredThe two-character ISO country code of the account holder's address.
BankDetailsobjectRequiredDetails about the bank account.
Child parameters1
BeneficiaryBankInformationobjectRequiredThe bank account to link.
Child parameters9
InstitutionNamestringRequiredName of the financial institution.
AccountTypestringRequiredThe type of the bank account given in
AccountNumber. It must beBUSINESS, in any case. A bank-debit link without it is refused withBeneficiaryBankInformation - AccountType is mandatory with value 'BUSINESS', and any other value withBeneficiaryBankInformation - AccountType must be with value 'BUSINESS'. Personal accounts not supported.Allowed values:
BUSINESS.CurrencystringRequiredThe three-letter ISO currency code of the bank account.
SWIFTBICstringOptionalSWIFT/BIC code of the bank. Required when the bank's country and currency 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.AccountNumberstringRequiredInstitution account identifier.
RoutingNumberstringOptionalFinancial institution routing number or other national bank code. Required when the bank's country and currency 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.CountryISO2stringRequiredThe two-character ISO country code of the bank's location.
EntityIDintegerOptionalThe ID of one of the entities of the account in
UserIDto link the bank to; an ID that isn't one of its entities fails with<EntityID> - Invalid Entity ID. Leave it out, as the example does, to use the account's default. See Entity IDs.RegulatoryFieldsobject[]Additional compliance data as
Key/Valuepairs. Send it only when a previous response lists a field whoseIsRegulatoryFieldistrue, with itsFieldNameas theKey.Child parameters2
KeystringOptionalThe parameter name of the additional compliance data.
ValuestringOptionalThe data value for
Key.
Response fields
LinkACHDebitBankBeneficiaryResponseobjectResponse wrapper.
Child parameters1
LinkACHDebitBankBeneficiaryResultobjectThe result of the operation.
Child parameters5
ACHDebitApprovalStatusstringThe bank's verification and approval status for bank debit funding. A new link starts as
Pending, or asPending - Microdeposit verfication(spelled that way) for a bank that Xtrm verifies with micro-deposits. You can fund from it onceGetACHDebitLinkedBankAccountsshowsApproved.AccountIdentityLevelstringThe identity level of the account in
UserID:Draft,Basic,StandardorAdvanced, from lowest to highest.BankBeneficiaryStatusstringThe status of the newly linked bank profile. A new link always returns
Pending.BeneficiaryIdstringThe unique identity code Xtrm generates for this linked bank profile.
OperationStatusobjectWhether the operation succeeded.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).ErrorsarrayValidation or execution error details when the call fails. When the bank needs more information, an array of objects, one per field to add or fix, each with
ErrorMessage,FieldName,FieldLabelandIsRegulatoryField; otherwise an array of message strings.nullwhen the call succeeds.
Related: Send micro-deposits to a linked bank · Verify micro-deposit amounts · List bank accounts linked for bank debit · Fund a wallet by bank debit · Delete a linked bank account
#Send micro-deposits to a linked bank
/API/v4/Bank/ReleaseACHDebitMicrodepositSends two small deposits to a linked bank account to confirm that Xtrm has connected your company to the right account. They can take up to 3 business days to show on the bank statement. Once they arrive, send both amounts to VerifyACHDebitMicrodeposit as Amount_1 and Amount_2 to verify the bank.
Pass the linked bank in BeneficiaryBankID. You get this ID when you link the bank with LinkACHDebitBankBeneficiary, or from GetACHDebitLinkedBankAccounts.
You release the micro-deposits once per bank: a second call returns Microdeposits were released. Please check your bank account.
Micro-deposits apply only to a bank whose LinkACHDebitBankBeneficiary response returned ACHDebitApprovalStatus Pending - Microdeposit verfication. Any other bank skips them: check GetACHDebitLinkedBankAccounts until it's Approved.
Note
The micro-deposits can take up to 3 business days to show on the bank statement.
Body parameters
ReleaseACHDebitMicrodepositobjectRequiredRequest wrapper, named after the operation.
Child parameters1
RequestobjectRequiredThe request fields. Note the capital
R.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.UserIDstringRequiredThe Xtrm account the bank is linked to, the same
UserIDyou sent toLinkACHDebitBankBeneficiary, starting withSPNfor company accounts orPATfor personal accounts. For a bank you fund your own wallets from, that's your ownSPN.BeneficiaryBankIDstringRequiredThe linked bank's
BeneficiaryId, returned when you link a bank or callGetACHDebitLinkedBankAccounts.
Response fields
ReleaseACHDebitMicrodepositResponseobjectResponse wrapper.
Child parameters1
ReleaseACHDebitMicrodepositResultobjectThe result of the operation.
Child parameters2
MessagestringA message confirming the micro-deposits, with the last four digits of the bank account number, for example
We have sent micro deposit to your account XXXX7890 successfully.OperationStatusobjectWhether the operation succeeded.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Validation or execution error details when the call fails.
nullwhen the call succeeds, so decide withSuccess.
Related: Link a bank account for bank debit funding · Verify micro-deposit amounts · List bank accounts linked for bank debit
#Verify micro-deposit amounts
/API/v4/Bank/VerifyACHDebitMicrodepositVerifies the two micro-deposits that ReleaseACHDebitMicrodeposit sent to the bank account. This confirms that you own the account and that it's linked correctly.
Pass the linked bank in BeneficiaryBankID, and the two micro-deposit amounts that appeared on the bank statement in Amount_1 and Amount_2. When the call succeeds, Message reads We have verified your bank successfully. and the bank's ACHDebitApprovalStatus turns Approved.
Tip
Send each amount as a string, for example "0.04", not as a number.
Note
Amounts that don't match return HTTP 400 with Invalid amount. or the bank provider's message, and an amount of 0 returns Amount_1 must be greater than 0 or Amount_2 must be greater than 0. If the amounts are refused too many times, delete the bank with DeleteBankBeneficiary and link it again.
Body parameters
VerifyACHDebitMicrodepositobjectRequiredRequest wrapper, named after the operation.
Child parameters1
RequestobjectRequiredThe request fields. Note the capital
R.Child parameters5
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.UserIDstringRequiredThe Xtrm account the bank is linked to, the same
UserIDyou sent toLinkACHDebitBankBeneficiary, starting withSPNfor company accounts orPATfor personal accounts. For a bank you fund your own wallets from, that's your ownSPN.BeneficiaryBankIDstringRequiredThe linked bank's
BeneficiaryId, returned when you link a bank or callGetACHDebitLinkedBankAccounts.Amount_1stringRequiredThe first micro-deposit amount that appeared on the bank statement, as a decimal string, for example
"0.04".Amount_2stringRequiredThe second micro-deposit amount that appeared on the bank statement, as a decimal string, for example
"0.07".
Response fields
VerifyACHDebitMicrodepositResponseobjectResponse wrapper.
Child parameters1
VerifyACHDebitMicrodepositResultobjectThe result of the operation.
Child parameters2
MessagestringA human-readable message confirming the result of the bank verification.
OperationStatusobjectWhether the operation succeeded.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Validation or execution error details when the call fails.
nullwhen the call succeeds, so decide withSuccess.
Related: Send micro-deposits to a linked bank · List bank accounts linked for bank debit · Fund a wallet by bank debit
#List bank accounts linked for bank debit
/API/v4/Bank/GetACHDebitLinkedBankAccountsReturns the bank accounts linked for bank debit (ACH, or bank transfer systems similar to ACH). You use these accounts to fund company wallets by bank debit.
Each linked bank account includes its BeneficiaryId and its ACHDebitApprovalStatus. A bank account whose ACHDebitApprovalStatus is Approved can fund a company wallet with FundWalletUsingACHDebit, which takes its BeneficiaryId as LinkedBankID. The list shows only banks linked for bank debit, not the banks linked to receive payments.
Tip
To remove a bank debit link, pass its ID to DeleteBankBeneficiary as BeneficiaryBankID.
Body parameters
GetACHDebitLinkedBankAccountsobjectRequiredRequest wrapper, named after the operation.
Child parameters1
requestobjectRequiredThe request fields.
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.RecipientUserIdstringRequiredThe Xtrm account whose bank-debit banks you list, starting with
SPNfor companies orPATfor personal accounts. To list the banks you fund your own wallets from, send your ownSPN. 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
GetACHDebitLinkedBankAccountsResponseobjectResponse wrapper.
Child parameters1
GetACHDebitLinkedBankAccountsResultobjectThe result of the operation.
Child parameters2
BeneficiaryobjectThe linked bank accounts.
Child parameters1
BeneficiaryDetailsobject[]One entry per linked bank account.
Child parameters7
BeneficiaryIdstringUnique identity code for the linked bank profile.
BeneficiaryNamestringName of the account holder on the bank account.
CurrencystringThe three-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
PaymentstringThe payment method, e.g.
ACH.
BankDetailsobjectDetails about the bank account.
Child parameters1
BeneficiaryBankInformationobjectThe linked bank account.
Child parameters8
AccountNumberstringBank account number. Masked in the example (
XXXX7890).BankNamestringBank name.
BranchNamestringBank branch identifier.
BankBeneficiaryStatusstringStatus of the linked bank profile:
ApprovedorPending.ACHDebitApprovalStatusstringApproval status of the bank debit link. It reads
Approvedonce the bank can fund a wallet. Until then it readsPending,Pending VerificationorPending Approval; a bank whose status isIncompleteorDeactivecan't be debited.BankRoutingCodestringRouting code of the bank.
EntityIDintegerA unique internal system identifier used to map this bank profile to a specific entity record.
PaymentMethodsobjectThe accepted payment methods.
nullin the example.
OperationStatusobjectWhether the operation succeeded.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Validation or execution error details when the call fails.
nullwhen the call succeeds, so decide withSuccess.
Related: Link a bank account for bank debit funding · Fund a wallet by bank debit · Send micro-deposits to a linked bank · Verify micro-deposit amounts · Delete a linked bank account