Initiate Batch Transfer

The Batch Transfer endpoint allows you to submit multiple individual transfer requests in one API call, each processed independently. Transfers can be either internal (between Netevia financial accounts) or ACH (to/from externally linked accounts). Each transfer in the batch requires source and destination account IDs, an amount, and a currency code. The entire batch request must be authenticated with a one-time verification code.

Endpoint

POST /api/fundsMovement/batch/transfer

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 you need to execute several transfers simultaneously — for example, disbursing funds to multiple business subprofile accounts, processing payroll distributions, or settling balances across a set of accounts in a single operation. Each transfer in the batch is evaluated independently, so partial success is possible. This endpoint requires step-up authentication via a one-time code, making it suitable for high-value or sensitive bulk operations.

Request Body

Transfer Request Object (transferRequests[])

{
  "oneTimeCode": "847291",
  "secureOperationType": "ShortMessageCode",
  "transferRequests": [
    {
      "fromFinancialAccountId": "fa_source_account_001",
      "toFinancialAccountId": "fa_destination_account_002",
      "amount": 5000,
      "currencyCode": 840,
      "type": "Netevia",
      "memo": "Monthly fee reimbursement"
    },
    {
      "fromFinancialAccountId": "fa_source_account_001",
      "toFinancialAccountId": "fa_external_linked_account_003",
      "amount": 12500,
      "currencyCode": 840,
      "type": "ACH",
      "memo": "Vendor payment batch June"
    }
  ]
}

Response

200 OK

Returns an array of results, one per transfer request submitted. Each result indicates success or failure for that individual transfer.

[
  {
    "id": "txn_7f3a2c1e4b8d9f0a",
    "response": "Transfer initiated successfully.",
    "errorCode": null
  },
  {
    "id": "txn_9b1d4e7f2c3a8e05",
    "response": "Transfer initiated successfully.",
    "errorCode": null
  }
]

Error Codes

Common Mistakes

• Sending oneTimeCode in a non-6-digit format — it must be exactly 6 numeric digits matching ^\d{6}$.
• Using a secureOperationType value other than ShortMessageCode, TimeBasedCode, or LegacyTimeBasedCode (case-sensitive enum).
• Setting amount to zero or omitting it when the receiving system expects a non-null value — minimum valid amount is 1 (smallest currency unit).
• Providing an unsupported currencyCode — only 840 (USD) is currently accepted.
• Mixing up type values: use Netevia for internal account-to-account transfers and ACH for transfers involving externally linked bank accounts.
• Using an expired or already-consumed oneTimeCode — codes are single-use and time-limited.
• Submitting an empty transferRequests array — include at least one transfer object to obtain meaningful results.

Related Endpoints

• POST /api/fundsMovement/transfer — Initiate a single funds transfer (non-batch)
• POST /api/fundsMovement/scheduled/transfer — Schedule a transfer for a future date
• POST /api/auth/v2 — Obtain a Bearer token for authentication
• POST /api/auth/refresh — Refresh an expiring Bearer token

Example

curl -X POST https://api.banking.netevia.dev/api/fundsMovement/batch/transfer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oneTimeCode": "847291",
    "secureOperationType": "ShortMessageCode",
    "transferRequests": [
      {
        "fromFinancialAccountId": "fa_source_account_001",
        "toFinancialAccountId": "fa_destination_account_002",
        "amount": 5000,
        "currencyCode": 840,
        "type": "Netevia",
        "memo": "Monthly fee reimbursement"
      },
      {
        "fromFinancialAccountId": "fa_source_account_001",
        "toFinancialAccountId": "fa_external_linked_account_003",
        "amount": 12500,
        "currencyCode": 840,
        "type": "ACH",
        "memo": "Vendor payment batch June"
      }
    ]
  }'