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 a Passport Account and an external bank account
• Enable treasury or liquidity management across accounts

Scenarios

Add a bank account the customer owns, then reuse it to move their own money. Every External Account follows the same lifecycle: create, validate, screen OFAC, activate. The validation method you choose (instant EWS, micro-deposit, or prenote) is covered on External Account Validations.

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: Save the US bank account you own

Add a bank account the customer holds at another US institution so you can move their own money in and out of their Passport Account: funding, transfers, and liquidity management. This example enables instant EWS validation so the account is usable within minutes; to choose micro-deposit or prenote instead, see External Account Validations.

You'll also need: EWS enabled for your program (check with your Program 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.

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:

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

1. EWS (validateAccount.ews=true)
   1. Instant validation
   2. Recommended for faster onboarding
2. Prenote
   1. Bank-level validation via zero-dollar transaction
   2. Takes 2-3 business days
3. 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:

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 your Program Manager 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