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

Field	Sub-field	Type/Enum	Description
resourceName	—	Enum	Always internationalExternalAccount
url	—	String	System-generated endpoint for this account
id	—	Long	Ahrvo-assigned unique identifier
externalId	—	String (≤ 45)	Program-manager reference (immutable, unique)
type	—	Enum	SAVINGS | 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	—	String	Length depends on country (e.g., AU 6, IN 11)
holderAddress	—	Object	addressLine1, addressLine2, city, state, country, zip
acceptedCurrency	—	Enum (3)	Acceptable currency/ies (see Appendix §12)
holderType	—	Enum	CONSUMER | CORPORATE
holderEmail	—	String	Valid email (e.g., abc@xyz.com)
holderPhone	—	Numeric	Holder phone number
additionalDetail.<key>	—	String	Dynamic keys (e.g., taxId) per country/currency
purpose	—	String	Cross-border compliance purpose code
accountNumberLast4	—	String	Last 4 digits (read-only)
status	—	Enum	See § 2.3
statusReason	—	Enum	Reason for current status
statusDate	—	Timestamp (UTC MM/DD/YYYY HH:MM:SS)
verification.ofacStatus	—	Enum	See § 2.3.2
verification.ofacStatusReason	—	Enum	Reason for OFAC status
verification.ofacStatusDate	—	Timestamp
metaData	—	Map	Key–value data (≤ 20 keys)
tags	—	String	Comma-separated labels
comment	—	String	User comments
createdOn / lastUpdatedOn	—	Timestamp	Creation / last update time (UTC)
createdBy / lastUpdatedBy	username, status	Object	User info

---

2.3 Statuses

2.3.1 International External Account Statuses

Status	Trigger
INACTIVE	Default on creation
ACTIVE	Passed OFAC verification
BLOCKED	OFAC manually rejected

2.3.2 OFAC Statuses

Status	Trigger
PENDING_VERIFICATION	Default on create / holder-name update
VERIFIED	OFAC check passed
UNDER_REVIEW	Automation unable to verify; manual review
REJECTED	OFAC disapproved by Ahrvo team
IGNORED	OFAC 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

Code	Message	Condition
EC-BL-9975	:[field] length should be :[value] for :[countryName]	Invalid international routing code length
EC-BL-9976	International 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

---