Connect Direct Deposit

The Connect Direct Deposit endpoint retrieves a secure, time-limited token used to initiate the Direct Deposit connection flow for a customer's financial account. Partners embed this token into a web view URL to allow customers to link their payroll or salary deposit directly to their Netevia banking account without additional paperwork. The token expires after a fixed period, ensuring sessions remain secure and short-lived.

Endpoint

GET /api/PinW/pinToken

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 connect a payroll or direct deposit source to their Netevia financial account via the EWA (Earned Wage Access) or Direct Deposit flow. The returned token must be embedded into the web view URL presented to the customer to complete the connection. Call this endpoint each time a new connection session is started, as tokens are time-limited and single-use per session.

Query Parameters

Parameter	Type	Required	Description
financialAccountId	string	Yes	The unique identifier of the financial account for which the Direct Deposit link token is being requested.

Response

200 OK

Field	Type	Description
data	object	Wrapper object containing the token session details.
data.mode	string	The operational mode of the session (e.g., `"sandbox"` or `"production"`).
data.id	string	A unique identifier for the token session.
data.token	string	The generated link token to be inserted into the Direct Deposit web view URL.
data.smartBranchUrl	string	URL for the smart branch web view flow; may be null depending on configuration.
data.expires	string (date-time)	ISO 8601 timestamp indicating when the token expires.

{
  "data": {
    "mode": "sandbox",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "smartBranchUrl": "https://connect.netevia.dev/link?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires": "2026-06-08T15:30:00Z"
  }
}

Error Codes

Code	When it happens
400	`financialAccountId` is missing, malformed, or does not belong to the authenticated customer.
401	Token missing, expired, or invalid.
403	Insufficient permissions to access the specified financial account.
404	Financial account not found for the given `financialAccountId`.
500	Internal server error.

Common Mistakes

Omitting financialAccountId in the query string — the parameter is required even though the schema does not mark it explicitly; requests without it will fail.
Reusing an expired token — tokens expire at the data.expires timestamp. Request a fresh token for each new connection session.
Not embedding the token into the web view URL before presenting it to the customer — the token must be included in the URL for the Direct Deposit connection flow to initialize correctly.
Calling this endpoint for personal customers who have not yet established a financial account — ensure the account exists and is active before requesting a link token.

Related Endpoints

POST /api/auth/v2 — Obtain a Bearer token for authenticating API requests.
POST /api/auth/refresh — Refresh an expiring Bearer token.
GET /api/PinW/accounts — List financial accounts available for Direct Deposit connection.

Example

curl -X GET "https://api.banking.netevia.dev/api/PinW/pinToken?financialAccountId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"