External Account Validations

Validating an external account helps:

• Reduce ACH return risks (e.g., insufficient funds, closed accounts)
• Prevent fraudulent activity
• Improve success rates of debit and credit transactions

Depending on your program configuration, validations can be triggered during account creation or later using the validation API. Multiple validation methods may be applied before an account becomes fully active.

Validation & Activation Lifecycle

When an external account is created, it moves through validation checks before reaching an active state. The diagram below shows the high-level flow:

flowchart TD
    A["POST /externalAccount<br/>(Account Created)"] --> B["INACTIVE<br/>status: PENDING_VERIFICATION"]

    B --> V{"Validations<br/>In Progress"}

    V --> EWS["1. EWS<br/>(Instant Validation)"]
    V --> PRE["2. Prenote<br/>(if ALWAYS / ON_FAILURE)"]
    V --> MD["3. Micro-Deposit<br/>(if ALWAYS)"]
    V --> OFAC["4. OFAC<br/>(Compliance Check)"]
    V --> DOC["5. Document Verification<br/>(Optional)"]

    EWS -->|"OPEN / VALIDATED"| PASS
    EWS -->|"NOT_FOUND / CLOSED / HIGH_RISK"| FAIL

    PRE -->|"COMPLETED"| PASS
    PRE -->|"FAILED"| FAIL

    MD -->|"AWAITING_VERIFICATION → COMPLETED"| PASS
    MD -->|"RETURNED / FAILED"| FAIL

    OFAC -->|"VERIFIED"| PASS
    OFAC -->|"UNDER_REVIEW / REJECTED"| FAIL

    DOC -->|"VERIFIED"| PASS
    DOC -->|"REJECTED"| FAIL

    PASS["All Validations<br/>Passed ✅"] --> ACTIVE["ACTIVE<br/>(Ready to transact)"]
    PASS --> CREDIT["ACTIVE<br/>(Credit Only)<br/>Debit restricted"]
    FAIL["Critical<br/>Failure ❌"] --> BLOCKED["BLOCKED"]

    style A fill:#e3f2fd,stroke:#1976d2
    style ACTIVE fill:#e8f5e9,stroke:#388e3c
    style CREDIT fill:#fff3e0,stroke:#f57c00
    style BLOCKED fill:#ffebee,stroke:#d32f2f
    style PASS fill:#e8f5e9,stroke:#388e3c
    style FAIL fill:#ffebee,stroke:#d32f2f

Validation Methods

Each validation method runs independently. Their combined results determine the final account status.

1. EWS (Early Warning Services) — Instant Validation

Validates account ownership at the financial institution in real time.

📘

Trigger: Set validateAccount: [{"ews": true}] during account creation or via the validate API.

2. Prenote — ACH Pre-notification

Sends a zero-dollar ACH entry to verify the routing and account number are valid.

📘

Trigger: Set prenote: "ALWAYS" or "ON_FAILURE" (falls back to prenote if EWS fails).

3. Micro-Deposit — Customer Verification

Sends two small credit amounts (e.g., $0.12, $0.34) to the customer's bank. The customer confirms the amounts to prove account ownership.

📘

Trigger: Set microDeposit: "ALWAYS" or "ON_FAILURE". Verify with POST .../verify endpoint.

4. OFAC — Compliance Screening

Screens the account holder name against the OFAC Specially Designated Nationals (SDN) list.

⚠️

OFAC screening runs automatically on every new external account. Accounts with UNDER_REVIEW or REJECTED status cannot transact until resolved.

5. Document Verification (Optional)

Validates authorization documents attached to the external account.

📘

Attach documents using the linkedDocument field with purpose: "AUTHORIZATION".

Final Account Status

The combined results of all validations determine the final account status:

Triggering Validations

At Account Creation

Include validation options in the POST /externalAccount request body:

{
  "accountNumber": "742019385624",
  "routingNumber": "021000021",
  "type": "CHECKING",
  "holderName": "Acme Corp",
  "holderType": "CORPORATE",
  "validateAccount": [{ "ews": true }],
  "microDeposit": "ALWAYS",
  "prenote": "ON_FAILURE"
}

After Account Creation

Use the validate API to trigger additional validations on an existing account:

POST /v1/customer/id/{customerId}/externalAccount/id/{id}/validate

{
  "validateAccount": [{ "ews": true }],
  "prenote": "NEVER",
  "microDeposit": "ALWAYS"
}

Best Practices