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.

Scenarios

Every External Account follows the same lifecycle — create, validate, screen OFAC, activate. Pick the scenario that matches your validation needs.

sequenceDiagram
    participant App as Your application
    participant PCE as PCE
    participant EWS as EWS / Bank
    participant OFAC as OFAC Screening
    
    App->>PCE: POST /externalAccount
    PCE->>PCE: Field validation
    PCE-->>App: 201 — status INACTIVE
    PCE->>EWS: Instant validation (EWS)
    EWS-->>PCE: Account valid
    PCE->>OFAC: Screen holder name
    OFAC-->>PCE: Cleared
    PCE-->>App: Webhook — status ACTIVE

Before you begin (all scenarios)

Customer exists and is ACTIVE.
You have the bank account number and 9-digit ACH routing number.
Account holder name matches bank records exactly.

Scenario 1: Add an External Account with Instant Validation (EWS)

Use this for the fastest onboarding experience. EWS validates the account instantly, and if successful, the account is ready for transactions within minutes.

You'll also need: EWS enabled for your program (check with your Account Manager).

Request

POST /v1/customer/id/48201/externalAccount

{
  "externalId": "ext-chase-001",
  "holderName": "Acme Corp",
  "holderType": "CORPORATE",
  "accountNumber": "123456789012",
  "routingNumber": "021000021",
  "type": "CHECKING",
  "validateAccount": [
    { "ews": true }
  ]
}

Response — 201 Created

Create returns 201 Created with an empty body; the new account ID is in the url (Location) response header. Retrieve the account to see its status and validation progress:

GET /v1/customer/id/48201/externalAccount/id/88712

{
  "resourceName": "externalAccount",
  "id": 88712,
  "externalId": "ext-chase-001",
  "holderName": "Acme Corp",
  "holderType": "CORPORATE",
  "accountNumberLast4": "9012",
  "routingNumber": "021000021",
  "status": "INACTIVE",
  "statusReason": "External Account Pending Verification",
  "verification": { "ofacStatus": "IGNORED" },
  "validateAccount": [
    { "ews": { "status": "PENDING", "statusReason": "PENDING" } }
  ]
}

If EWS returns OPEN, the account moves to ACTIVE after OFAC clears. Track status via webhooks.

Scenario 2: Add an External Account with Micro-Deposit Verification

Use this when you need strong ownership verification. Two small deposits ($0.12, $0.34) are sent to the account, and the customer must confirm the amounts.

You'll also need: Customer ability to view and report micro-deposit amounts (typically 2-3 business days).

Request

POST /v1/customer/id/48201/externalAccount

{
  "externalId": "ext-wells-001",
  "holderName": "Acme Corp",
  "holderType": "CORPORATE",
  "accountNumber": "987654321098",
  "routingNumber": "121000248",
  "type": "CHECKING",
  "microDeposit": "ALWAYS"
}

Response — 201 Created

Create returns 201 Created with an empty body. Retrieve the account to see its status and the micro-deposit validation state — the account stays INACTIVE until the deposits are confirmed:

GET /v1/customer/id/48201/externalAccount/id/88713

{
  "resourceName": "externalAccount",
  "id": 88713,
  "externalId": "ext-wells-001",
  "holderName": "Acme Corp",
  "holderType": "CORPORATE",
  "accountNumberLast4": "1098",
  "routingNumber": "121000248",
  "status": "INACTIVE",
  "statusReason": "External Account Pending Verification",
  "verification": { "ofacStatus": "IGNORED" },
  "microDeposit": { "microDepositValidation": "ALWAYS" }
}

After the customer confirms the deposit amounts via the verify API and OFAC clears, the account moves to ACTIVE.

Scenario 3: Add an External Account with Prenote (Zero-Dollar) Validation

Use this for bank-level validation without moving actual funds. A $0.00 transaction is sent through ACH to confirm the account exists and accepts credits/debits.

You'll also need: 2-3 business days for prenote to settle and return results.

Request

POST /v1/customer/id/48201/externalAccount

{
  "externalId": "ext-boa-001",
  "holderName": "Acme Corp",
  "holderType": "CORPORATE",
  "accountNumber": "456789012345",
  "routingNumber": "011401533",
  "type": "CHECKING",
  "prenote": "ALWAYS"
}

Response — 201 Created

Create returns 201 Created with an empty body. Retrieve the account to see its status and the prenote validation state — the account stays INACTIVE until the prenote settles:

GET /v1/customer/id/48201/externalAccount/id/88714

{
  "resourceName": "externalAccount",
  "id": 88714,
  "externalId": "ext-boa-001",
  "holderName": "Acme Corp",
  "holderType": "CORPORATE",
  "accountNumberLast4": "2345",
  "routingNumber": "011401533",
  "status": "INACTIVE",
  "statusReason": "External Account Pending Verification",
  "verification": { "ofacStatus": "IGNORED" },
  "prenote": { "prenoteValidation": "ALWAYS" }
}

Monitor webhooks for the prenote result. If successful, the account transitions to ACTIVE after OFAC clears.

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) `ON_FAILURE` – Run micro-deposit validation only if a prior validation method is inconclusive `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. Note: `linkedDocument` is an array — pass one object per document.
`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
`INACTIVE`	Default status on creation, while validations (EWS / Prenote / Micro-deposit) and OFAC screening are pending
`ACTIVE`	Successfully validated and OFAC-cleared; ready for transactions
`BLOCKED`	Restricted due to validation failure, OFAC/compliance concern, or a risk flag

Validation progress is tracked separately from the account status. Check the nested validateAccount[] (EWS), prenote, and microDeposit objects, plus verification.ofacStatus, in the retrieve response.

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 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