Get Payee by Financial Account
The GET /api/fundsMovement/Payee endpoint returns detailed information about a payee associated with a given financial account. Partners can use this endpoint to look up payee records, verify routing and account details before initiating ACH transfers, and surface payee data within their banking applications.
Endpoint
GET /api/fundsMovement/Payee
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.
When to use
Use this endpoint when a user needs to view or confirm the details of a payee before executing a funds movement transaction. It is useful during pre-transaction verification workflows, payee management screens, and audit processes where routing and account number accuracy is critical.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| financialAccountId | string | Yes | The unique identifier of the financial account whose associated payee should be retrieved. |
Response
200 OK
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier of the payee record. |
| name | string | Display name of the payee. |
| createdAt | string (date-time) | Timestamp when the payee was created. |
| updatedAt | string (date-time) | Timestamp when the payee record was last updated. Null if never updated. |
| accountNumber | string | Full account number associated with the payee. |
| routingNumber | string | ABA routing number for the payee's bank. |
| last4 | string | Last four digits of the payee's account number. |
| type | string | Internal type code for the payee. |
| typename | string | Human-readable type label for the payee (e.g., "Checking", "Savings"). |
{
"id": "payee_a1b2c3d4e5f6",
"name": "John Smith",
"createdAt": "2025-03-15T10:22:00Z",
"updatedAt": "2025-05-01T08:45:00Z",
"accountNumber": "XXXXXXXXXX",
"routingNumber": "021000021",
"last4": "4567",
"type": "ACH",
"typename": "Checking"
}Error Codes
| Code | When it happens |
|---|---|
| 400 | financialAccountId is missing, empty, or malformed. |
| 401 | Token missing, expired, or invalid. |
| 403 | Insufficient permissions to access payee data for the specified financial account. |
| 404 | No payee found for the provided financialAccountId. |
| 500 | Internal server error. |
Common Mistakes
- Omitting
financialAccountIdfrom the query string — the parameter is required even though the schema does not explicitly mark it as such; the call will fail or return no data without it. - Using a financial account ID that belongs to a different partner or customer — the endpoint enforces ownership scoping and will return 403 or 404.
- Displaying the raw
accountNumbervalue in a UI — use thelast4field for masked display and reserve the full number only for backend processing.
Related Endpoints
POST /api/fundsMovement/Payee— Add a new payee to a financial account.DELETE /api/fundsMovement/Payee— Remove a payee from a financial account.GET /api/fundsMovement/Transfer— Retrieve transfer history for a financial account.POST /api/fundsMovement/Transfer— Initiate an ACH or internal transfer to a payee.
Example
curl -X GET "https://api.banking.netevia.dev/api/fundsMovement/Payee?financialAccountId=fa_1234567890abcdef" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json"