Batch Adding External Banking Account Number - Payee

This endpoint allows partners to register multiple external bank accounts as payees in a single batch operation. Each account in the batch is linked by routing number, account number, and account type, and the entire request is secured with a one-time verification code. This approach reduces round-trip overhead when onboarding several payee accounts at once.

Endpoint

POST /api/fundsMovement/batch/externalPayee

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 needs to add multiple external bank accounts as payees simultaneously — for example, during initial onboarding of a business customer who pays multiple vendors, or when migrating an existing set of payee accounts into the Netevia platform. The batch operation combines all account additions into a single secure, verified transaction, reducing the number of OTP prompts required compared to adding each payee individually.

Request Body

{
  "requests": [
    {
      "routingNumber": "021000021",
      "accountNumber": "XXXXXXXXXX",
      "name": "Vendor Payroll Account",
      "bankAccountType": "CHECKING"
    },
    {
      "routingNumber": "011401533",
      "accountNumber": "XXXXXXXXXX",
      "name": "Supplier Savings Account",
      "bankAccountType": "SAVINGS"
    }
  ],
  "oneTimeCode": "847291",
  "secureOperationType": "ShortMessageCode"
}

Response

200 OK

Returns an array of result objects, one per submitted payee account request.

[
  {
    "mainNode": {
      "typename": "AddNonVerifiedExternalUSFinancialBankAccount",
      "id": "extacct_01HX9KZQV3MTNR8WPBFYG2C4D",
      "name": "Vendor Payroll Account",
      "externalBankAccountDetails": {
        "last4": "7890",
        "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": []
    }
  },
  {
    "mainNode": {
      "typename": "AddNonVerifiedExternalUSFinancialBankAccount",
      "id": "extacct_02JY0LARGS4NUTS9XQCGZH3E5F",
      "name": "Supplier Savings Account",
      "externalBankAccountDetails": {
        "last4": "3412",
        "type": "SAVINGS",
        "routingNumber": "011401533",
        "accountNumber": "XXXXXXXXXX",
        "createdAt": "2026-06-08T14:22:11Z",
        "updatedAt": "2026-06-08T14:22:11Z"
      },
      "accessDeniedErrorMessage": null,
      "createdAt": "2026-06-08T14:22:11Z",
      "updatedAt": "2026-06-08T14:22:11Z",
      "errors": []
    },
    "mutationResult": {
      "errors": []
    }
  }
]

Error Codes

Common Mistakes

• Providing a oneTimeCode that does not exactly match the pattern ^\d{6}$ (e.g., including spaces, letters, or fewer/more than 6 digits) will cause a 400 validation error.
• Setting bankAccountType to a value other than SAVINGS or CHECKING (case-sensitive) will fail validation — do not use lowercase or mixed-case variants.
• Omitting the top-level oneTimeCode or secureOperationType fields, which are required at the batch level even if individual items carry their own OTP fields.
• Sending raw, unmasked account numbers in logs or error reports — always sanitize account numbers as XXXXXXXXXX in any diagnostic output.
• Assuming a 200 response means all items succeeded — always inspect each item's mainNode.errors and mutationResult.errors arrays for per-item failures within a successful batch response.

Related Endpoints

• POST /api/fundsMovement/externalPayee — Add a single external bank account as a payee.
• GET /api/fundsMovement/externalPayees — List all external payee accounts for the current customer.
• DELETE /api/fundsMovement/externalPayee/{id} — Remove a specific external payee account.
• POST /api/fundsMovement/transfer — Initiate a funds transfer to a registered external payee.

Example

curl -X POST https://api.banking.netevia.dev/api/fundsMovement/batch/externalPayee \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "routingNumber": "021000021",
        "accountNumber": "XXXXXXXXXX",
        "name": "Vendor Payroll Account",
        "bankAccountType": "CHECKING"
      },
      {
        "routingNumber": "011401533",
        "accountNumber": "XXXXXXXXXX",
        "name": "Supplier Savings Account",
        "bankAccountType": "SAVINGS"
      }
    ],
    "oneTimeCode": "847291",
    "secureOperationType": "ShortMessageCode"
  }'