Add External Banking Account Number - Payee

This endpoint allows an authenticated user to register an external bank account as a payee for funds movement before the account has been fully verified. The account is stored immediately but remains in an unverified state until the user completes a separate verification step. Once verified, the external account becomes eligible for ACH transfers and other payment operations.

Endpoint

POST /api/fundsMovement/v2/connectNonVerifiedExternalBankAccount

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a customer wants to link an external bank account as a payee but the account has not yet undergone micro-deposit or other verification. This is typically the first step in a two-phase flow: connect the account now, then verify it later before initiating any transfers. This approach allows the payee relationship to be established immediately while deferring the verification ceremony to a convenient time.

Request Body

{
  "routingNumber": "021000021",
  "accountNumber": "XXXXXXXXXX",
  "name": "Acme Corp Operating Account",
  "bankAccountType": "CHECKING",
  "oneTimeCode": "847293",
  "secureOperationType": "ShortMessageCode"
}

Response

200 OK

{
  "mainNode": {
    "typename": "AddNonVerifiedExternalUSFinancialBankAccount",
    "id": "ext-acct-7f3a2b9c-1d45-4e78-b012-abc123def456",
    "name": "Acme Corp Operating Account",
    "externalBankAccountDetails": {
      "last4": "6789",
      "type": "CHECKING",
      "routingNumber": "021000021",
      "accountNumber": "XXXXXXXXXX",
      "createdAt": "2026-06-08T14:22:10Z",
      "updatedAt": "2026-06-08T14:22:10Z"
    },
    "accessDeniedErrorMessage": null,
    "createdAt": "2026-06-08T14:22:10Z",
    "updatedAt": "2026-06-08T14:22:10Z",
    "errors": []
  },
  "mutationResult": {
    "errors": []
  }
}

Error Codes

Common Mistakes

• Providing a bankAccountType value other than the exact strings SAVINGS or CHECKING (the field is case-sensitive and validated against that pattern).
• Sending a oneTimeCode that is not exactly 6 digits or contains non-numeric characters — the pattern ^\d{6}$ is strictly enforced.
• Attempting to use the newly added external account for a transfer immediately; the account must complete verification first before it can be used for funds movement.
• Omitting secureOperationType or using a value not in the allowed enum (ShortMessageCode, TimeBasedCode, LegacyTimeBasedCode).
• Logging or storing the raw accountNumber in plaintext; always mask as XXXXXXXXXX in logs and audit trails.

Related Endpoints

• POST /api/fundsMovement/v2/connectExternalBankAccount — Connect and verify an external bank account in a single step using Finicity or Plaid
• GET /api/fundsMovement/v2/getExternalBankAccounts — Retrieve all external bank accounts linked to the authenticated customer
• DELETE /api/fundsMovement/v2/removeExternalBankAccount — Remove a linked external bank account
• POST /api/fundsMovement/v2/transferToExternalBankAccount — Initiate an ACH transfer to a verified external bank account

Example

curl -X POST https://api.banking.netevia.dev/api/fundsMovement/v2/connectNonVerifiedExternalBankAccount \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "routingNumber": "021000021",
    "accountNumber": "XXXXXXXXXX",
    "name": "Acme Corp Operating Account",
    "bankAccountType": "CHECKING",
    "oneTimeCode": "847293",
    "secureOperationType": "ShortMessageCode"
  }'