Add a new Netevia's account number - Payee.

Add Payee

This endpoint allows an authenticated user to register a new payee on their account for use in funds movement operations. The payee is a Netevia account holder to whom the user can send funds via account-to-account transfers or bill payments. Adding a payee requires verification via a one-time code to confirm the operation is authorized.

Endpoint

POST /api/fundsMovement/v2/Payee

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 user wants to designate a new recipient account for outgoing fund transfers. Once a payee is added, it can be referenced in future A2A transfers and payment operations without re-entering the account details. This step is required before initiating any transfer to a new Netevia account that has not been previously registered as a payee.

Request Body

{
  "accountNumber": "XXXXXXXXXX",
  "name": "Acme Corp Payroll",
  "oneTimeCode": "482917",
  "secureOperationType": "ShortMessageCode"
}

Response

200 OK

{
  "message": "Payee successfully added.",
  "payeeId": "pye_0f3a21bc7d4e5f6a",
  "payeeName": "Acme Corp Payroll",
  "accountNumber": "XXXXXXXXXX",
  "isExternalAccount": false
}

Error Codes

Common Mistakes

• Providing a oneTimeCode that is not exactly 6 digits — the field requires the pattern ^\d{6}$ and will be rejected otherwise.
• Omitting secureOperationType or passing a value not in the allowed enum (ShortMessageCode, TimeBasedCode, LegacyTimeBasedCode), which causes a 400 validation error.
• Attempting to add a payee with an account number already registered on the account, resulting in a 409 Conflict response.
• Using an expired Bearer token — tokens last 10 minutes; refresh before making this call if the token may have elapsed.

Related Endpoints

• GET /api/fundsMovement/v2/Payee — Retrieve the list of payees registered on the account
• DELETE /api/fundsMovement/v2/Payee/{payeeId} — Remove an existing payee from the account
• POST /api/fundsMovement/v2/Transfer — Initiate a funds transfer to a registered payee

Example

curl -X POST https://api.banking.netevia.dev/api/fundsMovement/v2/Payee \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "XXXXXXXXXX",
    "name": "Acme Corp Payroll",
    "oneTimeCode": "482917",
    "secureOperationType": "ShortMessageCode"
  }'