Initiate Transfer Between Financial Accounts

This endpoint initiates a secure transfer of funds between two financial accounts within the Netevia Banking platform. The caller specifies the source account, destination account, transfer amount, and an optional memo to describe the transaction. Upon success, the API returns a transaction reference ID and status that can be used to track the transfer.

Endpoint

POST /api/fundsMovement/v2/initiateTransferBetweenFinancialAccounts

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 move funds between two financial accounts that are already registered on the Netevia platform — for example, transferring money between a customer's checking and savings accounts, or between accounts belonging to the same business entity. This endpoint supports both personal and business account transfers. For transfers involving externally linked accounts (via Finicity or Plaid), use the appropriate ACH transfer endpoints instead.

Request Body

{
  "fromFinancialAccountId": "fa_source_account_id_here",
  "toFinancialAccountId": "fa_destination_account_id_here",
  "amount": 25000,
  "currencyCode": 840,
  "memo": "Monthly savings transfer"
}

Response

200 OK

{
  "initiateTransferBetweenFinancialAccounts": {
    "id": "txn_0a1b2c3d4e5f6a7b8c9d0e1f",
    "createdAt": "2026-06-08T14:32:00Z",
    "updatedAt": "2026-06-08T14:32:01Z",
    "amount": {
      "value": 25000,
      "currencyCode": "USD"
    },
    "status": "PENDING",
    "statusReason": "Transfer is being processed",
    "memo": "Monthly savings transfer",
    "errors": []
  },
  "mutationResult": {
    "errors": []
  }
}

Error Codes

Common Mistakes

• Submitting amount as a decimal (e.g., 250.00) instead of the integer value in cents (e.g., 25000). The field is int32 and represents the smallest currency unit.
• Using an unsupported currencyCode value. Currently only 840 (USD) is accepted.
• Including disallowed characters in the memo field (e.g., hyphens, slashes, or special symbols). Only alphanumeric characters, periods, and spaces are permitted.
• Attempting to transfer to/from an account that belongs to a different customer without proper authorization.
• Providing an amount of 0 — the minimum accepted value is 1.

Related Endpoints

• POST /api/fundsMovement/v2/initiateACHTransfer — Initiate an ACH transfer using an externally linked account via Finicity or Plaid
• POST /api/fundsMovement/v2/initiateScheduledTransfer — Schedule a recurring or future-dated transfer between financial accounts
• POST /api/fundsMovement/v2/initiateBatchTransfer — Submit multiple transfer instructions in a single batch request
• GET /api/fundsMovement/v2/getTransferStatus — Retrieve the current status of a previously initiated transfer

Example

curl -X POST https://api.banking.netevia.dev/api/fundsMovement/v2/initiateTransferBetweenFinancialAccounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromFinancialAccountId": "fa_source_account_id_here",
    "toFinancialAccountId": "fa_destination_account_id_here",
    "amount": 25000,
    "currencyCode": 840,
    "memo": "Monthly savings transfer"
  }'