Skip to main content

Overview

An international external account is any bank account that exists outside the Ahrvo system and supports cross-border electronic fund transfers. Each account is linked to a customer and undergoes an OFAC check on the holder name before transactions can be processed.

  • A customer may register multiple international external accounts.
  • All printable ASCII characters are allowed in string fields unless stated otherwise.

Example – A customer’s Wells Fargo account in the US from which Ahrvo can debit or credit funds.


2.2 Attributes​

FieldSub-fieldType/EnumDescription
resourceName—EnumAlways internationalExternalAccount
url—StringSystem-generated endpoint for this account
id—LongAhrvo-assigned unique identifier
externalId—String (≤ 45)Program-manager reference (immutable, unique)
type—EnumSAVINGS | CHECKING
holderName—String (≤ 60)Name on bank records (no ~ or ` chars)
accountNumber—String (≤ 34)Bank account number; letters, numbers, *:#-/&,+’
swiftCode—String (8-11)SWIFT/BIC code
internationalRoutingCode—StringLength depends on country (e.g., AU 6, IN 11)
holderAddress—ObjectaddressLine1, addressLine2, city, state, country, zip
acceptedCurrency—Enum (3)Acceptable currency/ies (see Appendix §12)
holderType—EnumCONSUMER | CORPORATE
holderEmail—StringValid email (e.g., abc@xyz.com)
holderPhone—NumericHolder phone number
additionalDetail.<key>—StringDynamic keys (e.g., taxId) per country/currency
purpose—StringCross-border compliance purpose code
accountNumberLast4—StringLast 4 digits (read-only)
status—EnumSee § 2.3
statusReason—EnumReason for current status
statusDate—Timestamp (UTC MM/DD/YYYY HH:MM:SS)
verification.ofacStatus—EnumSee § 2.3.2
verification.ofacStatusReason—EnumReason for OFAC status
verification.ofacStatusDate—Timestamp
metaData—MapKey–value data (≤ 20 keys)
tags—StringComma-separated labels
comment—StringUser comments
createdOn / lastUpdatedOn—TimestampCreation / last update time (UTC)
createdBy / lastUpdatedByusername, statusObjectUser info

2.3 Statuses​

2.3.1 International External Account Statuses​

StatusTrigger
INACTIVEDefault on creation
ACTIVEPassed OFAC verification
BLOCKEDOFAC manually rejected

2.3.2 OFAC Statuses​

StatusTrigger
PENDING_VERIFICATIONDefault on create / holder-name update
VERIFIEDOFAC check passed
UNDER_REVIEWAutomation unable to verify; manual review
REJECTEDOFAC disapproved by Ahrvo team
IGNOREDOFAC check disabled

2.4 Business Validations​

  1. externalId must be unique and is immutable.
  2. An international external account can be deleted only if no transactions exist.
  3. Only accounts in INACTIVE status may be updated.
  4. Account is set to BLOCKED if OFAC is rejected.
  5. PO Box addresses are not allowed for the holder address.
  6. Meta Data API (see § 4.6.6) must be run once before creating the first non-USD account for a given country/currency to fetch dynamic field requirements.

2.5 Error Codes & Messages​

CodeMessageCondition
EC-BL-9975:[field] length should be :[value] for :[countryName]Invalid international routing code length
EC-BL-9976International Routing Code is required for Country : :[value]Missing routing code
EC-BL-0538“Account with same number and routing code already exists.”Duplicate account
EC-VA-0005“PO Box addresses are not allowed…”Holder address is a PO Box
EC-BL-10362“Delete not allowed on Non USD accounts.”Attempt to delete non-USD account
EC-BL-10355“Update not allowed on Non USD accounts.”Attempt to update non-USD account
EC-BL-10359{"field":"taxID","message":"taxID is mandatory…"}Missing country-specific field
EC-BL-0005{"field":"acceptedCurrency", …}Missing mandatory fields

2.6 Operations Supported​

  • Create International External Account
  • Update International External Account
  • Retrieve International External Account
  • Retrieve All International External Accounts
  • List International External Accounts