Initiate transfer funds between financial accounts - Payee.

Initiate Payee Transfer

The Payee Transfer endpoint enables users to securely send funds from their financial account to a payee's account within the Netevia banking system. The request requires multi-factor verification via a one-time code to ensure the transaction is authorized. Upon successful initiation, the API returns a confirmation with the transaction details including status and payee account information.

Endpoint

POST /api/fundsMovement/v2/PayeeTransfer

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 send funds to a payee account — for example, paying a vendor, an individual, or processing a business-to-business payment. This endpoint is appropriate for both personal transfers and business transactions where the destination account is registered as a payee in the system. Always obtain and supply a fresh one-time verification code before calling this endpoint, as the request will fail if the code is missing or expired.

Request Body

{
  "fromFinancialAccountId": "fa_source_abc123",
  "toFinancialAccountId": "fa_payee_xyz789",
  "amount": 5000,
  "currencyCode": 840,
  "memo": "Invoice payment Oct 2025",
  "oneTimeCode": "847291",
  "secureOperationType": "ShortMessageCode"
}

Response

200 OK

A successful response confirms that the payee transfer has been initiated. The response body contains the transaction confirmation details.

{
  "transactionId": "txn_98f2e4c1a7b345d9",
  "status": "Pending",
  "fromFinancialAccountId": "fa_source_abc123",
  "toFinancialAccountId": "fa_payee_xyz789",
  "amount": 5000,
  "currencyCode": 840,
  "memo": "Invoice payment Oct 2025",
  "createdAt": "2025-10-15T14:32:00Z"
}

Error Codes

Common Mistakes

• Providing an amount of 0 — the minimum allowed value is 1. Amount must be expressed in the smallest currency unit (cents), so $50.00 should be sent as 5000.
• Sending a oneTimeCode that is expired or already used — obtain a fresh code immediately before each transfer request, as codes are single-use and time-limited.
• Using an unsupported secureOperationType value — only ShortMessageCode, TimeBasedCode, and LegacyTimeBasedCode are accepted.
• Including special characters in the memo field — only word characters (a-z, A-Z, 0-9, _), periods, and spaces are permitted.
• Omitting currencyCode when the destination account may require it — supplying 840 (USD) explicitly avoids ambiguity.

Related Endpoints

• POST /api/fundsMovement/v2/Transfer — Initiate an internal transfer between a user's own financial accounts
• POST /api/fundsMovement/v2/ScheduledTransfer — Schedule a future-dated transfer to a payee or own account
• POST /api/fundsMovement/v2/BatchTransfer — Submit multiple transfer requests in a single batch operation
• POST /api/auth/v2 — Obtain a Bearer token required for authentication
• POST /api/auth/refresh — Refresh an existing Bearer token before expiry

Example

curl -X POST https://api.banking.netevia.dev/api/fundsMovement/v2/PayeeTransfer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromFinancialAccountId": "fa_source_abc123",
    "toFinancialAccountId": "fa_payee_xyz789",
    "amount": 5000,
    "currencyCode": 840,
    "memo": "Invoice payment Oct 2025",
    "oneTimeCode": "847291",
    "secureOperationType": "ShortMessageCode"
  }'