Generate financial account connect link. Callback example [CallbackURL]?id=&status=success&accounts=[{bankName,routing,account}]

Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

Connect Financial Account

Generates a time-limited, secure URL that redirects a merchant to the Finicity financial account connection flow. After the merchant completes the bank account linking process, Finicity calls back to the provided callbackUrl with the result. The callback includes the merchant ID, a status indicator, and an array of connected bank account details.

Callback format: [callbackUrl]?id=&status=success&accounts=[{bankName,routing,account}]

Endpoint

GET /api/v1/connectFinancialAccount

Authentication

Basic HTTP Authentication required.
Encode username:password in Base64 and pass in the Authorization header:

Authorization: Basic {base64(username:password)}

When to use

Use this endpoint during the merchant boarding process when bank account verification is required. The generated link should be presented to the merchant (typically embedded in a boarding portal or emailed as a direct link). The link is time-limited, so it should be consumed promptly after generation. Once the merchant completes the flow, the system receives the bank account data via the callback URL, which you control.

Query Parameters

Parameter	Type	Required	Description
id	integer (int32)	Yes	The merchant profile ID for the existing merchant whose financial account is being connected
callbackUrl	string	Yes	The URL that Finicity will call after the merchant completes the account connection flow

Response

200 OK

Field	Type	Description
data	string	The secure Finicity URL for the merchant to use to connect their bank account
status	string	HTTP status label (e.g., `OK`)
error	string	Error message if link generation failed
warning	string	Non-fatal warning message, if any
validationResults	array	List of validation errors
requestId	integer	Unique identifier for this API request

{
  "data": "https://connect2.finicity.com?customerId=5839201&origin=url&partnerId=4567&signature=a3f9b2c1d4e5&timestamp=1716912000&ttl=1716915600&webhook=https%3A%2F%2Fhq.netevia.com%2Fapi%2Fwebhook%2Ffinicity&webhookContentType=application%2Fjson",
  "status": "OK",
  "error": null,
  "warning": null,
  "validationResults": [],
  "requestId": 90128
}

Error Codes

Code	When it happens
400	`id` or `callbackUrl` parameter is missing or invalid
401	Invalid or missing Basic Auth credentials
403	User does not have permission for this operation
404	Merchant with the specified `id` not found
500	Internal server error

Common Mistakes

Providing a callbackUrl that is not publicly accessible — Finicity must be able to reach this URL from their servers; localhost URLs will not work in production.
Not URL-encoding the callbackUrl when including it as a query parameter — ensure special characters are percent-encoded.
Reusing an expired link — generate a fresh link for each session since Finicity links are time-limited (ttl field in the URL).
Checking connectivity status before the merchant has completed the Finicity flow — use GET /api/v1/getAccountConnectivityStatus only after the callback has been received.

Related Endpoints

GET /api/v1/getAccountConnectivityStatus — check whether the merchant's Finicity connection is active
GET /api/v1/merchant/status — check the overall boarding status of the merchant
POST /api/v1/merchant/create — create the merchant profile before generating the connect link

Example

curl -X GET "https://hq.staging.netevia.dev/api/v1/connectFinancialAccount?id=48291&callbackUrl=https%3A%2F%2Fyourapp.example.com%2Ffinicity%2Fcallback" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"