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:

sequenceDiagram
    participant App as Your application
    participant PCE as PCE
    participant Bank as EWS / Bank
    participant Cust as Customer

    App->>PCE: Create external account (validation options)
    PCE-->>App: status INACTIVE (PENDING_VERIFICATION)

    PCE->>Bank: EWS instant validation
    alt EWS returns OPEN
        Bank-->>PCE: Account valid
    else EWS inconclusive (ON_FAILURE fallback)
        Bank-->>PCE: NOT_FOUND / high-risk
        PCE->>Bank: Prenote (zero-dollar)
        Bank-->>PCE: Prenote result
    end

    opt Micro-deposit (ALWAYS)
        PCE->>Cust: Send two micro-deposits
        Cust-->>PCE: Confirm amounts (verify API)
    end

    Note over PCE: Combine method results + OFAC into a final status

    alt Debit + credit checks pass
        PCE-->>App: Webhook — ACTIVE (full debit & credit)
    else Debit check fails, credit passes
        PCE-->>App: Webhook — ACTIVE (Credit only, debit restricted)
    else Critical failure (OFAC rejected / EWS high-risk)
        PCE-->>App: Webhook — BLOCKED
    end

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