Skip to main content

Overview

An external account is any bank account that exists outside the Ahrvo Banking system. It is linked to a customer to collect funds into the customer’s account via funding sources such as ACH, Wire, or Check. Customers can configure one or more external accounts. Every external account undergoes OFAC name checks for transaction processing.

Example: A customer’s Wells Fargo bank account from which they agree to debit or credit funds.

2. Attributes​

FieldSub-fieldTypeDescription
resourceName—String (Enum)Always externalAccount.
id—LongUnique identifier assigned by Ahrvo Banking.
externalId—String (≤45 chars)Reference ID assigned by the program manager.
holderName—String (≤128 chars)Account holder name (printable ASCII except ~ and |).
holderPhone—StringHolder’s phone number.
holderAddress.addressLine1—String (≤35 chars)Address line 1.
holderAddress.addressLine2—String (≤35 chars)Address line 2.
holderAddress.city—String (≤25 chars)City.
holderAddress.state—String (2 chars)State.
holderAddress.zip—String (5 or 9 digits)ZIP code.
accountNumber—String (≤40 chars)Full bank account number (letters, digits, *:#-/&,+’).
accountNumberLast4—StringLast four digits of the account number.
routingNumber—String (9 chars)ACH routing number.
wireRoutingNumber—String (9 chars)Wire routing number (if different).
type—EnumAccount type (e.g., CHECKING).
holderType—EnumHolder type (e.g., INDIVIDUAL, BUSINESS).
purpose—StringPurpose of linking this account.
validateAccount.status—String (Enum)EWS validation status.
validateAccount.statusReason—StringEWS validation reason.
validateAccount.statusDate—TimestampEWS validation date.
prenoteValidation—String (Enum)Prenote mode: ALWAYS, NEVER, ON_FAILURE.
prenote.status—StringPrenote status.
prenote.statusReason—StringPrenote reason.
prenote.statusDate—TimestampPrenote date.
microDepositValidation—String (Enum)Micro-deposit mode: ALWAYS, NEVER.
microDeposit.status—StringMicro-deposit status.
microDeposit.statusReason—StringMicro-deposit reason.
microDeposit.statusDate—TimestampMicro-deposit date.
bankInfo.contactNumber—StringBank’s contact number.
bankInfo.name—StringBank’s name.
bankInfo.address—StringBank’s address.
bankInfo.routingNumber—StringBank’s routing number.
status—String (Enum)Current external account status.
statusReason—StringReason for current status.
statusDate—TimestampDate of current status.
verification.ofacStatus—StringOFAC verification status.
verification.ofacStatusReason—StringOFAC status reason.
verification.ofacStatusDate—TimestampOFAC status date.
metaData—MapKey/value store (max 20 keys).
tags—[String]Labels assigned to this external account.
linkedDocument.id—StringDocument ID.
linkedDocument.purpose—String (Enum)AUTHORIZATION.
linkedDocument.document.resourceName—StringAlways document.
linkedDocument.document.url—StringDocument URL.
linkedDocument.document.id—StringDocument reference ID.
linkedDocument.document.externalId—StringDocument external ID.
linkedDocument.document.type—StringDocument type (e.g., SPAA).
linkedDocument.document.name—StringDocument filename.
linkedDocument.document.base64EncodedContent—StringBase64-encoded file content.
linkedDocument.linkedOn—TimestampUpload timestamp (MM/DD/YYYY HH:mm:ss UTC).
linkedBy.userType—StringUser type who linked the document.
linkedBy.username—StringUsername who linked the document.
linkedBy.status—StringUser status.
validateInstantly.status—StringInstant-validation status (Ahrvo Account).
validateInstantly.statusReason—StringInstant-validation reason.
validateInstantly.statusDate—TimestampInstant-validation date.
comment—StringUser comments.
createdOn—TimestampCreation timestamp.
createdBy.username—StringCreator username.
createdBy.status—StringCreator status.
lastUpdatedOn—TimestampLast update timestamp.
lastUpdatedBy.username—StringUpdater username.
lastUpdatedBy.status—StringUpdater status.

3. Statuses​

External Account Statuses​

StatusStatus ReasonEvents responsible
INACTIVEPending VerificationDefault on creation.
PENDING_VERIFICATIONPending VerificationVerification in progress.
ACTIVE—Successful OFAC/validation.
BLOCKEDVarious (e.g., R02, manual)Returns on collect/prenote/micro; manual block; account closed via instant validation.

OFAC Statuses​

StatusEvents responsible
PENDING_VERIFICATIONDefault on create/update if OFAC enabled.
VERIFIEDSuccessful OFAC verification.
UNDER_REVIEWAutomation failed; manual review.
REJECTEDManual OFAC disapproval.
IGNOREDOFAC disabled by program manager.

Linked Document Statuses​

StatusEvents responsible
PENDING VERIFICATIONDefault on document upload.
VERIFIEDReviewer-approved.
REJECTEDReviewer-rejected.

EWS Statuses & Status Reasons​

StatusReason
PENDINGPending
NOT_FOUNDAccount not found/undetermined
CLOSEDAccount closed/Pending closure
HIGH_RISKStop payment requested/negative balance
INVALID_DEBIT_ACCOUNTNo debits accepted
OPENActive, good standing
VALIDATEDValidated and in good standing

Prenote Statuses & Status Reasons​

StatusReasonDescription
PENDINGPENDINGScheduled prenote not yet in transit.
PROCESSINGPROCESSINGPrenote in transit.
COMPLETEDCOMPLETEDPrenote succeeded; account info valid.
FAILEDRETURNEDPrenote failed; bank return code (e.g., account closed).
NOT_REQUIREDNOT_REQUIREDSkipped due to instant validation block.

Micro Deposit Statuses & Status Reasons​

StatusReasonDescription
PENDINGPENDINGMicro-deposit not yet in transit.
AWAITING_VERIFICATIONPROCESSINGMicro-deposit in transit.
VERIFIEDVERIFIEDMicro-deposit succeeded; account info valid.
VERIFICATION_FAILEDVERIFICATION FAILEDMicro-deposit failed after max attempts.
NOT_REQUIREDNOT_REQUIREDSkipped due to instant validation block.

Instant Validation Statuses & Status Reasons​

StatusReasonDescription
PENDINGPENDINGUnder instant validation.
OPENVERIFIED_BY_SYSTEMAhrvo account instantly validated.
INVALID_DEBIT_ACCOUNTNo debits acceptedAhrvo account accepts only credits.
VERIFICATION_FAILEDVERIFICATION FAILEDName mismatch on Ahrvo account.
BLOCKEDAccount blocked/inactiveAhrvo account is BLOCKED or INACTIVE.
NOT_FOUNDAccount not foundNo matching Ahrvo account found.

4. Business Validations​

  • externalId must be unique and immutable.
  • Cannot create duplicate account (same number, routing & type) for same owner.
  • In INACTIVE status, any field may be updated; in ACTIVE, only holderName and purpose.
  • Only one of prenote or micro-deposit validations allowed.
  • Validation methods enabled by program manager only.
  • Accounts activate post successful OFAC or validation.
  • Manually BLOCKED accounts may be unblocked (returns to PENDING_VERIFICATION).
  • External account may be deleted if no transactions exist.
  • Verified documents cannot be deleted.

5. Error Codes & Messages​

Error CodeError MessageCondition
EC-BL-0003ExternalAccount with external reference: <external-id> already exists.Duplicate externalId.
EC-BL-0004Routing Number: <routing-number> does not exist.Invalid ACH routing number.
EC-BL-0004Wire Routing Number: <routing-number> does not exist.Invalid wire routing number.
EC-VA-0005{"errorCode":"EC-VA-0005","errorMessage":"Validation failed.","errors":[{"field":"<field>","message":"Is required."}]}Missing mandatory field.
EC-BL-2344Either prenote or micro deposit is allowed.Both validation methods requested simultaneously.
EC-BL-0525Details entered do not match; you have {attempts_remaining} attempts left.Micro-deposit verify amounts mismatch.
EC-BL-0526Maximum no. of attempts reached; account verification failed.Micro-deposit attempts exhausted.

6. Operations​

  • Create External Account
  • Update External Account
  • Retrieve External Account by id
  • Delete External Account
  • Retrieve all External Accounts linked to a Customer
  • List External Accounts
  • Validate External Account
  • Verify External Account