This guide covers practical tips for integrating Flinks Upload into your application, including submission modes, data consumption patterns, and handling edge cases.
Integration modes for submitting documents
There are three ways users can submit documents to Flinks Upload:
| Mode | Description | Best for |
|---|
| Connect Widget (Primary) | Upload option displayed alongside bank linking after institution selection | Maximum coverage — users choose between linking or uploading |
| Connect Widget (Fallback) | Upload option appears only after a failed bank login attempt | Keeping bank linking as the primary flow |
| Dashboard | Manual upload through the Flinks Dashboard | Back-office or support-initiated uploads |
Integration modes for consuming data
| Mode | Description |
|---|
| API | Call /GetAccountsDetail to retrieve extracted transaction and account data programmatically |
| Dashboard | View extracted data and fraud signals visually in the Flinks Dashboard |
Fallback triggers
When Upload is configured as a fallback in Flinks Connect, the upload option appears automatically when the user encounters one of these connection errors:
| Error code | Description |
|---|
INVALID_USERNAME | The username entered was not recognized |
INVALID_PASSWORD | The password entered was incorrect |
INVALID_LOGIN | Generic login failure |
DISABLED_LOGIN | The user’s online banking access is disabled |
RETRY_LATER | The financial institution is temporarily unavailable |
SESSION_EXPIRED | The session timed out during authentication |
INVALID_SECURITY_RESPONSE_NO_RETRY | Security question answered incorrectly with no retry allowed |
AGGREGATION_ERROR | A general error occurred during data aggregation |
Force-upload shortcut
You can send users directly to the upload flow for a specific financial institution by appending /upload/[Institution Name] to your Flinks Connect URL:
https://[instance]-iframe.private.fin.ag/v2/upload/[Institution Name]
Async handling with webhooks
Flinks Upload processes documents asynchronously. Rather than polling the API for results, configure webhooks to receive a notification when processing completes.
Use webhooks over polling. Webhook-based async handling is the recommended pattern for Upload. It reduces unnecessary API calls and delivers results as soon as they’re ready.
Credit union member numbers
For credit union accounts, member numbers may be displayed with suffixes that indicate the account type:
| Suffix | Account type |
|---|
-0 | Chequing / share draft |
-1 | Savings |
-2, -3, etc. | Additional accounts |
xxxx2354-0 indicates a chequing account, while xxxx2354-1 indicates a savings account under the same membership.
Multiple files in one upload
When a user uploads multiple PDF files in a single submission, they count as one upload against your quota. You don’t need to have users submit files one at a time — up to 24 files (180 MB total) can be included in a single upload.
