External Accounts represent bank accounts owned by the customer but held outside the Priority's PCE system. These accounts are linked to enable movement of funds between the customer’s own accounts across different financial institutions.

A customer can configure one or more external accounts, depending on their business needs.

When to Use External Accounts

Transfer funds between your own bank accounts
Move funds between Passport account and external bank account
Enable treasury or liquidity management across accounts

External Accounts should not be used for collecting funds from or sending funds to third parties. Use Contacts (Payees) for such flows.

How it Works

Add an External Account Provide bank account details such as account number, routing number, and account holder information.
Verification & Validation

External accounts undergo validation based on program configuration:
- EWS (Early Warning Services) → 🆕 Instant account validation
- Prenote (0-dollar transaction) → 🆕 Takes 2–3 business days
- Micro-deposit validation → 🆕 Takes 2–3 business days The validation method and sequence are configurable at program level. Refer to External Account Validations to learn more about each of these methods.
OFAC Screening The account holder’s name is screened against regulatory and compliance watchlists.
Account Activation Once verification and compliance checks are successfully completed, the external account is marked as ACTIVE and is ready for transactions.

Add an External Account

Use the POST /v1/customer/id/{id}/externalAccount (or using externalId) API to add an external bank account within the system. Key Details Required:

Field	Required	Description
`holderName`	✓	Name of the account holder exactly as per bank records
`holderType`	✓	Indicates whether the account belongs to an `CONSUMER` or a `CORPORATE`.
`accountNumber`	✓	Bank account number to be linked
`routingNumber`	✓	9-digit ACH routing number used for bank transfers. Use the POST `/v1/bank/list` API to retrieve a list of bank routing numbers along with their corresponding financial institution details, based on the specified search criteria.
`wireRoutingNumber`	Optional	Routing number used for wire transfers, if different from ACH routing number
`type`	✓	Type of bank account - `CHECKING` or `SAVINGS`.
`validateAccount.ews`	Optional	Enables instant account validation using EWS. Values: `true` – Perform instant validation during account creation (recommended for faster onboarding) `false` – Skip EWS validation If not provided, the system applies the default configuration set for your program.
`microDeposit`	Optional	Enables validation via micro-deposits to confirm account ownership. Values: `ALWAYS` – Always validate using micro-deposits (recommended when strong ownership verification is required) `NEVER` – Do not perform micro-deposit validation (recommended when relying on other validation methods) If not provided, the system applies the default configuration.
`prenote`	Optional	Enables validation via prenote (zero-dollar transaction). Values: `ALWAYS` – Always run prenote validation (recommended for bank-level validation without moving funds) `NEVER` – Skip prenote validation `ON_FAILURE` – Run prenote only if EWS validation returns `NOT_FOUND` (use as a fallback when instant validation is inconclusive) If not provided, the system applies the default configuration.
`linkedDocument.purpose`	Optional	Defines the purpose of the document. Example: `AUTHORIZATION` – indicates user consent for debiting/crediting the account
`linkedDocument.document.type`	Optional	Type of supporting document uploaded. Values: `ATD` – Account Transfer Document (authorizes fund movement) `EFT` – Electronic Funds Transfer authorization form `SPAA` – Signed Payment Authorization Agreement `WEB_RECEIPT` – Online consent or transaction receipt `TEL_RECEIPT` – Consent captured via phone interaction `DMF` – Document Management Form for internal/reference use `ACCOUNT_SETUP_FORM` – Form used to collect account details during onboarding

Validations can be triggered during account creation or post creation using the v1/customer/id/{id}/externalAccount/id/{id}/validate API. For more details, refer to External Account Validations.

After submitting the request, the system checks that all required information is present. If any validation fails, the request is rejected immediately, and an error response is returned. You must correct the issue and resubmit the request. For a complete list of validation errors and how to resolve them, refer to the HTTP Response Codes.

Key Capabilities:

Link multiple external accounts per customer
Enable fund movement between own accounts via ACH/Wire rails
Attach authorization documents
Perform configurable validations (EWS, Prenote, Micro-deposit)
Maintain compliance and verification status

Validation Configuration

EWS (validateAccount.ews=true)
1. Instant validation
2. Recommended for faster onboarding
Prenote
1. Bank-level validation via zero-dollar transaction
2. Takes 2–3 business days
Micro-deposit
1. Verifies ownership via small deposits
2. Takes 2–3 business days

The system may use a fallback approach (e.g., EWS → Prenote on failure) based on configuration.

Retrieve External Account details

Use the GET v1/customer/id/{id}/externalAccount/id/{id} API to view the following important information:

External Account Status & Status Reason: Current state of the external account along with the reason (e.g., ACTIVE, BLOCKED due to insufficient funds or validation failure)
Validation Statuses: Results of validations performed on the account, including:
- EWS (instant validation)
- Prenote
- Micro-deposit
OFAC Status: Compliance verification status of the account holder (e.g., VERIFIED, UNDER_REVIEW, REJECTED)
Instant Validation Details: Outcome of internal validation (e.g., OPEN, NOT_FOUND, INVALID_DEBIT_ACCOUNT)
Linked Document Status: Status of any supporting documents submitted (e.g., PENDING_VERIFICATION, VERIFIED, REJECTED)
Timestamps: Key lifecycle timestamps such as creation date, last updated date, and status change date

Only the last 4 digits of the account number are returned in API responses for security.

External Account Lifecycle

External Accounts follow a defined lifecycle based on validation and compliance outcomes:

Status	Description
`PENDING`	Account created but validations are pending
`IN_VERIFICATION`	Validation in progress (EWS / Prenote / Micro-deposit)
`ACTIVE`	Successfully validated and ready for transactions
`BLOCKED`	Account restricted due to risk, validation failure, or compliance issue
`REJECTED`	Account failed validation or compliance checks

Blocked Accounts & Resolution

An external account may be marked as BLOCKED due to:

Failed validation (EWS / Prenote / Micro-deposit)
OFAC or compliance concerns
Incorrect or inconsistent account details
Risk flags raised during transactions

Resolution Path

Review statusReason from the GET v1/customer/id/{id}/externalAccount/id/{id} API response.
Correct account details if required
Re-initiate validation using the v1/customer/id/{id}/externalAccount/id/{id}/validate API endpoint.
Contact PayOps or the PCE Account Management team for compliance-related blocks

Transactions are not allowed on blocked accounts

Compliance & Security

Every external account undergoes OFAC verification.
Transactions are allowed only after successful validations.
Supporting documents can be used for authorization and audit purposes.

Best Practices

Practice	Description
Use External Accounts only for self-owned accounts	Do not use for third-party transfers
Prefer EWS for faster onboarding	Instant validation reduces delays
Use fallback validations when needed	Prenote or micro-deposit for stronger verification
Monitor account status regularly	Identify blocked or failed accounts early
Store externalAccountId	Required for future transactions