API reference

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/LinkACHDebitBankBeneficiary

Links 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.

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

  • LinkACHDebitBankBeneficiaryobjectRequired

    Request wrapper, named after the operation.

    Child parameters1
    • requestobjectRequired

      The request fields.

      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

        The Xtrm account the bank is linked to, starting with SPN for a company account or PAT for a personal account: your own company, or an account connected to it. To fund your own wallets, send your own SPN: FundWalletUsingACHDebit debits only a bank linked to the company in its IssuerAccountNumber. 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 account holder and the bank account to link.

        Child parameters2
        • BeneficiaryDetailsobjectRequired

          Details about the account holder.

          Child parameters1
          • BeneficiaryInformationobjectRequired

            The account holder's name, phone number and address.

            Child parameters8
            • ContactNamestringRequired

              The account holder's name, 1 to 100 characters. It can't contain special characters such as <, >, @, #, $ or %.

            • PhoneNumberstringRequired

              The account holder's phone number, as a string of 1 to 15 characters. Spaces, dashes and other formatting characters count toward the 15.

            • AddressLine1stringRequired

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

            • AddressLine2stringOptional

              Additional address details for the account holder, such as apartment or suite.

            • CitystringRequired

              The account holder's city, 1 to 100 characters.

            • RegionstringRequired

              The account holder's region or state, as either the two-letter ISO2 code or the full state name.

            • PostalCodestringRequired

              ZIP code or other postal code for the account holder.

            • CountryISO2stringRequired

              The two-character ISO country code of the account holder's address.

        • BankDetailsobjectRequired

          Details about the bank account.

          Child parameters1
          • BeneficiaryBankInformationobjectRequired

            The bank account to link.

            Child parameters9
            • InstitutionNamestringRequired

              Name of the financial institution.

            • AccountTypestringRequired

              The type of the bank account given in AccountNumber. It must be BUSINESS, in any case. A bank-debit link without it is refused with BeneficiaryBankInformation - AccountType is mandatory with value 'BUSINESS', and any other value with BeneficiaryBankInformation - AccountType must be with value 'BUSINESS'. Personal accounts not supported.

              Allowed values: BUSINESS.

            • CurrencystringRequired

              The three-letter ISO currency code of the bank account.

            • SWIFTBICstringOptional

              SWIFT/BIC code of the bank. Required when the bank's country and currency 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

              Institution account identifier.

            • RoutingNumberstringOptional

              Financial 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 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

              The two-character ISO country code of the bank's location.

            • EntityIDintegerOptional

              The ID of one of the entities of the account in UserID to 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/Value pairs. Send it only when a previous response lists a field whose IsRegulatoryField is true, with its FieldName as the Key.

              Child parameters2
              • KeystringOptional

                The parameter name of the additional compliance data.

              • ValuestringOptional

                The data value for Key.

Response fields

  • LinkACHDebitBankBeneficiaryResponseobject

    Response wrapper.

    Child parameters1
    • LinkACHDebitBankBeneficiaryResultobject

      The result of the operation.

      Child parameters5
      • ACHDebitApprovalStatusstring

        The bank's verification and approval status for bank debit funding. A new link starts as Pending, or as Pending - Microdeposit verfication (spelled that way) for a bank that Xtrm verifies with micro-deposits. You can fund from it once GetACHDebitLinkedBankAccounts shows Approved.

      • AccountIdentityLevelstring

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

      • BankBeneficiaryStatusstring

        The status of the newly linked bank profile. A new link always returns Pending.

      • BeneficiaryIdstring

        The unique identity code Xtrm generates for this linked bank profile.

      • OperationStatusobject

        Whether the operation succeeded.

        Child parameters2
        • Successboolean

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

        • Errorsarray

          Validation 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, FieldLabel and IsRegulatoryField; otherwise an array of message strings. null when 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

POST/API/v4/Bank/ReleaseACHDebitMicrodeposit

Sends 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

  • ReleaseACHDebitMicrodepositobjectRequired

    Request wrapper, named after the operation.

    Child parameters1
    • RequestobjectRequired

      The request fields. Note the capital R.

      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

        The Xtrm account the bank is linked to, the same UserID you sent to LinkACHDebitBankBeneficiary, starting with SPN for company accounts or PAT for personal accounts. For a bank you fund your own wallets from, that's your own SPN.

      • BeneficiaryBankIDstringRequired

        The linked bank's BeneficiaryId, returned when you link a bank or call GetACHDebitLinkedBankAccounts.

Response fields

  • ReleaseACHDebitMicrodepositResponseobject

    Response wrapper.

    Child parameters1
    • ReleaseACHDebitMicrodepositResultobject

      The result of the operation.

      Child parameters2
      • Messagestring

        A 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.

      • OperationStatusobject

        Whether the operation succeeded.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

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

Related: Link a bank account for bank debit funding · Verify micro-deposit amounts · List bank accounts linked for bank debit

#Verify micro-deposit amounts

POST/API/v4/Bank/VerifyACHDebitMicrodeposit

Verifies 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

  • VerifyACHDebitMicrodepositobjectRequired

    Request wrapper, named after the operation.

    Child parameters1
    • RequestobjectRequired

      The request fields. Note the capital R.

      Child parameters5
      • 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

        The Xtrm account the bank is linked to, the same UserID you sent to LinkACHDebitBankBeneficiary, starting with SPN for company accounts or PAT for personal accounts. For a bank you fund your own wallets from, that's your own SPN.

      • BeneficiaryBankIDstringRequired

        The linked bank's BeneficiaryId, returned when you link a bank or call GetACHDebitLinkedBankAccounts.

      • Amount_1stringRequired

        The first micro-deposit amount that appeared on the bank statement, as a decimal string, for example "0.04".

      • Amount_2stringRequired

        The second micro-deposit amount that appeared on the bank statement, as a decimal string, for example "0.07".

Response fields

  • VerifyACHDebitMicrodepositResponseobject

    Response wrapper.

    Child parameters1
    • VerifyACHDebitMicrodepositResultobject

      The result of the operation.

      Child parameters2
      • Messagestring

        A human-readable message confirming the result of the bank verification.

      • OperationStatusobject

        Whether the operation succeeded.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

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

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

POST/API/v4/Bank/GetACHDebitLinkedBankAccounts

Returns 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

  • GetACHDebitLinkedBankAccountsobjectRequired

    Request wrapper, named after the operation.

    Child parameters1
    • requestobjectRequired

      The request fields.

      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

        The Xtrm account whose bank-debit banks you list, starting with SPN for companies or PAT for personal accounts. To list the banks you fund your own wallets from, send your own SPN. 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

  • GetACHDebitLinkedBankAccountsResponseobject

    Response wrapper.

    Child parameters1
    • GetACHDebitLinkedBankAccountsResultobject

      The result of the operation.

      Child parameters2
      • Beneficiaryobject

        The linked bank accounts.

        Child parameters1
        • BeneficiaryDetailsobject[]

          One entry per linked bank account.

          Child parameters7
          • BeneficiaryIdstring

            Unique identity code for the linked bank profile.

          • BeneficiaryNamestring

            Name of the account holder on the bank account.

          • Currencystring

            The 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

              The payment method, e.g. ACH.

          • BankDetailsobject

            Details about the bank account.

            Child parameters1
            • BeneficiaryBankInformationobject

              The linked bank account.

              Child parameters8
              • AccountNumberstring

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

              • BankNamestring

                Bank name.

              • BranchNamestring

                Bank branch identifier.

              • BankBeneficiaryStatusstring

                Status of the linked bank profile: Approved or Pending.

              • ACHDebitApprovalStatusstring

                Approval status of the bank debit link. It reads Approved once the bank can fund a wallet. Until then it reads Pending, Pending Verification or Pending Approval; a bank whose status is Incomplete or Deactive can't be debited.

              • BankRoutingCodestring

                Routing code of the bank.

              • EntityIDinteger

                A unique internal system identifier used to map this bank profile to a specific entity record.

              • PaymentMethodsobject

                The accepted payment methods. null in the example.

      • OperationStatusobject

        Whether the operation succeeded.

        Child parameters2
        • Successboolean

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

        • Errorsstring[]

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

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