Initiate Many Transfers Between Financial Accounts - Payee

This endpoint enables users to submit multiple internal financial account transfers to various payees in a single API call. Each transfer in the batch is processed individually and returns its own success or failure result. This method is particularly useful for automating large-scale fund disbursements, such as paying multiple vendors or distributing payments to clients simultaneously.

Endpoint

POST /api/fundsMovement/PayeeTransferMany

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 business needs to disburse funds to multiple payees at once rather than issuing individual transfer requests. This is ideal for payroll-adjacent disbursements, vendor batch payments, or any workflow that requires high-volume fund movement in a single operation. Each transfer in the batch is tracked independently, allowing granular visibility into which transfers succeeded or failed.

Request Body

{
  "transferRequests": [
    {
      "fromFinancialAccountId": "fa-source-001-abc123",
      "toFinancialAccountId": "fa-vendor-001-xyz789",
      "amount": 50000,
      "currencyCode": 840,
      "memo": "Vendor payment Q2"
    },
    {
      "fromFinancialAccountId": "fa-source-001-abc123",
      "toFinancialAccountId": "fa-vendor-002-def456",
      "amount": 75000,
      "currencyCode": 840,
      "memo": "Contractor payout June"
    }
  ],
  "oneTimeCode": "482917",
  "secureOperationType": "ShortMessageCode"
}

Response

200 OK

Returns an array of objects, one per submitted transfer request, each indicating the result of that individual transfer.

[
  {
    "id": "txn-00a1b2c3-d4e5-6789-fghi-jklmnopqrstu",
    "response": "Transfer initiated successfully.",
    "errorCode": null
  },
  {
    "id": "txn-11b2c3d4-e5f6-7890-ghij-klmnopqrstuv",
    "response": "Transfer initiated successfully.",
    "errorCode": null
  }
]

Error Codes

Common Mistakes

• Submitting an oneTimeCode that is not exactly 6 digits — the pattern ^\d{6}$ is strictly enforced and will cause a 400 error.
• Using the wrong secureOperationType for the code you received — ensure the value matches the method that generated the OTP (e.g., use ShortMessageCode for SMS-delivered codes).
• Setting amount to 0 or omitting it and assuming a default — amounts must be between 1 and 4,294,967,295 (in the smallest currency unit, i.e., cents for USD).
• Reusing the same oneTimeCode across multiple requests — one-time codes are single-use and expire quickly.
• Including an unsupported currencyCode — only 840 (USD) is currently accepted.

Related Endpoints

• POST /api/fundsMovement/PayeeTransfer — Initiate a single transfer to a payee financial account
• POST /api/fundsMovement/TransferMany — Initiate multiple transfers between internal financial accounts (non-payee)
• POST /api/fundsMovement/Transfer — Initiate a single transfer between internal financial accounts
• POST /api/auth/v2 — Obtain a Bearer authentication token

Example

curl -X POST https://api.banking.netevia.dev/api/fundsMovement/PayeeTransferMany \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transferRequests": [
      {
        "fromFinancialAccountId": "fa-source-001-abc123",
        "toFinancialAccountId": "fa-vendor-001-xyz789",
        "amount": 50000,
        "currencyCode": 840,
        "memo": "Vendor payment Q2"
      },
      {
        "fromFinancialAccountId": "fa-source-001-abc123",
        "toFinancialAccountId": "fa-vendor-002-def456",
        "amount": 75000,
        "currencyCode": 840,
        "memo": "Contractor payout June"
      }
    ],
    "oneTimeCode": "482917",
    "secureOperationType": "ShortMessageCode"
  }'