Validate External Accounts

Verify and activate external accounts with multiple validation methods

Ensure that a bank account is valid, and safe to transact before using it for any debits or credits.

External account verification in PCE operates across three layers:

  1. Account Validation: Validates whether the bank account exists and is operational.
  2. Ownership Verification: Confirms that the account belongs to the intended customer.
  3. Risk & Transaction Signals: Evaluates whether the account can safely support transactions (e.g., sufficient balance, return risks).

Each of these layers contributes to the final External Account Status.

This page explains:

  • Verification methods and their flows
  • Status journeys across different validation methods
  • What each status means and when action is required

How Verification Works

  • External account is created → INACTIVE
  • Verification is initiated → PENDING_VERIFICATION
  • One or more validation methods are executed:
    • Instant validation (EWS / internal match)
    • Prenote
    • Micro-deposit
  • OFAC screening runs in parallel
  • Based on outcomes:
    • Success → ACTIVE
    • Limited → ACTIVE (Credit Only)
    • Failure → BLOCKED

External Account Status (Primary Status)

This is the external account's status that determines whether the account can be used.

StatusWhat it MeansWhen it HappensAction Required
INACTIVEAccount created but not yet verifiedDefault on creationTrigger verification
PENDING_VERIFICATIONVerification in progressValidation initiatedWait / monitor
ACTIVEAccount verified and usableSuccessful validationNone
ACTIVE (Credit Only)Only credits allowed, debits restrictedEWS / R01 scenariosInform user / retry later
BLOCKEDAccount cannot be usedFailures, returns, manual blockRe-verify or update details

Verification Methods & Their Status Journeys

Each method has its own lifecycle and outcomes.

Always monitor External Account Status + Method Status together

1. Instant Validation (EWS / Internal Matching)

Best for: Real-time validation

Status Journey

PENDING → OPEN / VALIDATED
       → NOT_FOUND
       → INVALID_DEBIT_ACCOUNT
       → CLOSED / HIGH_RISK

Statuses Explained

StatusMeaningAction
PENDINGValidation in progressWait
OPEN / VALIDATEDAccount is validProceed to activation
NOT_FOUNDAccount not recognizedTrigger fallback (Prenote/Micro-deposit)
INVALID_DEBIT_ACCOUNTCannot debitAllow credits only
CLOSED / HIGH_RISKRisky or closed accountBlock account

2. Prenote Verification

Best for: Bank-level validation without moving funds

Status Journey

PENDING → PROCESSING → COMPLETED
                        ↓
                     FAILED

Statuses Explained

StatusMeaningAction
PENDINGNot yet initiatedWait
PROCESSINGIn transitWait
COMPLETEDSuccessfully validatedActivate account
FAILED (RETURNED)Bank rejectedBlock / re-enter details
NOT_REQUIREDSkipped due to prior failureNo action

3. Micro-deposit Verification

Best for: Ownership confirmation

Status Journey

PENDING → PROCESSING → AWAITING_VERIFICATION → COMPLETED
                                      ↓
                                  RETURNED / VERIFICATION_FAILED

Statuses Explained

StatusMeaningAction
PENDINGNot initiatedWait
PROCESSINGDeposit sentWait
AWAITING_VERIFICATIONAwaiting user confirmationPrompt user to verify
COMPLETEDVerified successfullyActivate account
RETURNEDBank rejected depositBlock / retry
VERIFICATION_FAILEDMax attempts reachedRestart verification
NOT_REQUIREDSkipped due to earlier failureNo action

Instant Internal Validation (Passport Account Matching)

Status Journey

PENDING → OPEN
       → INVALID_DEBIT_ACCOUNT
       → VERIFICATION_FAILED
       → BLOCKED
       → NOT_FOUND

Statuses Explained

StatusMeaningAction
OPENMatched with Passport accountInstantly activate
INVALID_DEBIT_ACCOUNTDebit restrictedCredit-only usage
VERIFICATION_FAILEDName mismatchCorrect holder details
BLOCKEDAccount restrictedDo not proceed
NOT_FOUNDNo match foundUse alternate verification

OFAC Verification Status

Compliance layer that runs parallel to account validation.

StatusMeaningAction
PENDING_VERIFICATIONAwaiting checkWait
VERIFIEDPassed complianceProceed
UNDER_REVIEWManual review requiredMonitor
REJECTEDFailed complianceDo not proceed
IGNOREDNot applicableNone

Linked Document Status

StatusMeaningAction
PENDING_VERIFICATIONAwaiting reviewWait
VERIFIEDApprovedNone
REJECTEDRejectedUpload new document

Failure Handling & Re-verification

Common Failure Scenarios

Insufficient Funds / Returns (e.g., R01)

  • Account may be marked Credit Only
  • Debits are restricted temporarily, Retry debit later

Account Closed / Invalid (e.g., R02)

  • External account is moved to BLOCKED
  • No further transactions allowed
  • User must add a new account

Verification Failures

  • Micro-deposit / Prenote failures → BLOCKED
  • User may need to re-add or re-verify account

Automatic Re-verification

  • If EWS = NOT_FOUND → fallback to Prenote or Micro-deposit
  • If verification fails → account may require re-creation
  • If manually unblocked → returns to PENDING_VERIFICATION

Important Rules

  • Only one validation method (Prenote or Micro-deposit) can be used
  • External accounts are activated only after successful verification
  • Duplicate accounts (same number + routing + type) are not allowed
  • Verified documents cannot be deleted

Best Practices

  • Prefer Instant Validation for faster onboarding
  • Use Micro-deposit when ownership confirmation is critical
  • Monitor status transitions via Retrieve API
  • Handle BLOCKED accounts gracefully in your UI

Pending

  • Instant Ownership Verification (GIACT)
  • Concept of Vault?
  • Concept of Instant Ownership Verification (EWS / Internal Matching) needs to be validated

.readme-logo { display: none !important; }