Distribute lending through intermediaries

Intermediary distribution lets a partner submit loan applications while the lender keeps product configuration, decision-making, lending, and servicing in Finsaku. A partner can work in the Finsaku portal or submit through a separately implemented external-system adapter.

For

Tenant, access, product, and integration administrators preparing an intermediary channel.

Requires

Permission to maintain groups, queries, intermediaries, users, products, and any optional integration.

Available when

The lending product and its active version are ready for controlled application testing.

Start and duration

Agree the partner's allowed tasks, prohibited tasks, data, products, and status updates. Allow 45–90 minutes for a portal role and query, excluding integration development and organisational approval.

Finish state

A partner can submit an in-scope application and follow its status without seeing another intermediary's applications or internal lending controls.

Choose the distribution channel

Channel	How applications enter Finsaku	How the partner follows progress	Additional work
Finsaku portal	An affiliated user starts and submits the application in New Application.	A Partner application query shows applications submitted by that affiliation.	Configure the intermediary, group, users, query, product, and fields.
External partner system	A deployment-specific adapter validates the partner request and submits it using a dedicated Finsaku API identity affiliated with that intermediary.	The adapter can return a response and send status callbacks. Finsaku event actions can also call a webhook for supported application events.	Design, implement, secure, monitor, and test the adapter and callback contract.
Both	Portal users and the adapter create applications under the same intermediary boundary.	The portal query and external callbacks use the same application status as their source.	Test both entry points and prevent duplicate submissions across them.

Creating an intermediary does not create a partner-facing API endpoint. The external-system channel is an integration project with its own request contract, authentication, error handling, and operating owner.

How the controls fit together

Control	Purpose
Intermediary	Records the partner organisation and holds its affiliated users and assigned permission groups.
Affiliation	Identifies the intermediary represented by a signed-in portal or API user.
Permission group	Supplies the operations available to the intermediary and its users. Access from other active groups is cumulative.
Partner application query	Supplies the partner's application list. For a partner-restricted user, Finsaku adds the current affiliation as a Submitter condition.
Seller and Submitter	A new application started by an affiliated user receives the current affiliation in both roles. Partner application-query scoping uses Submitter.
Product and fields	Define selectable lending terms and the data collected from the partner. Field display conditions can simplify the partner form but do not replace record permissions.
Event action or adapter	Sends data to an external endpoint after a supported event, when an external status update is required.

Intermediary application flow

Portal

IntermediaryAffiliated user

Start application→

ApplicationSubmitter set

Submit→

LenderInternal review

Status changes→

Partner queryStatus visible

External

Partner systemApplication request

Authenticate and map→

AdapterAffiliated API user

Create application→

LenderInternal review

Notify outcome→

Partner systemCallback received

Inquiry, rejection, and approval are alternate review outcomes. Lend is a separate internal action that creates the loan after approval.

Define the partner boundary

Write down the intended and prohibited tasks before assigning permissions. A common division is:

Partner role	Internal role
Create, save, and submit an application.	Review submitted data and request clarification.
Add the agreed supporting information and files.	Run internal checks and record the decision.
View the status and agreed result fields for its applications.	Approve, reject, and, for an authorised lender, use Lend.
Correct an application when the configured workflow permits it.	Maintain the resulting loan, schedule, payments, and exceptions.

Keep loan and payment access internal unless the deployment has a separately verified partner-scoping control for those records. The automatic affiliation condition described on this page applies to Loan Application queries; it does not establish the same boundary for Loans, Payments, or every API operation.

Create the partner permission group

1. Open Administration → Add Group.
2. Give the group a name that describes the intermediary task, not a specific individual.
3. Select the application list, read, create, update, and processing permissions needed for the agreed portal workflow.
4. Add List Partner Queries.
5. Do not add List Internal Queries to the partner role.
6. Leave approval, lending, loan servicing, payment, export, user administration, configuration, and impersonation permissions out unless each operation is required and separately tested.
7. Select Add, then reopen the group and review its effective permissions.

The partner affiliation condition is applied when the user has List Partner Queries and does not have List Internal Queries. Because permissions are cumulative, review every active group assigned directly to the user and through the intermediary. Receiving List Internal Queries from any of them removes the automatic partner restriction.

Create the partner application query

1. Open Administration → Add Query.
2. Select Loan Application as the Query Object.
3. Enter a clear name and translations for the partner list.
4. Set Visibility to Partner.
5. Under Visible In, select Tree Menu and only the other locations required by the partner workflow.
6. Add the minimum columns needed to identify an application and understand its status.
7. Add only approved search fields and filters. Enable export only if partner export has been approved and tested.
8. Select Add and test the resulting list as a partner-affiliated user.

The affiliation condition matches the current user's affiliation to the application's Submitter. Do not add a broad alternate condition that bypasses that relationship. Direct application access also checks whether a non-tenant affiliation is involved in the application, but lists, global search, embedded queries, direct links, and exports must still be tested separately.

Create the intermediary and users

1. Open Administration → Add Intermediary and create one record for the partner organisation.
2. Under Login, assign the partner permission group, then select Add.
3. Open the intermediary and check the group in Groups.
4. In Users, select Create for a new affiliated portal user or Assign for an existing active user without another intermediary affiliation.
5. Reopen each user and confirm Status, Affiliation, and Groups.

Use a separate named user for each person. Use a separate non-interactive identity for an external adapter. Do not share a portal user's credentials with an integration.

Configure the product and partner form

1. Confirm that the intended lending product has an active version and can be selected in New Application.
2. Review the application fields required from the partner and the data kept for internal review.
3. Apply tested field display conditions where internal-only fields should not appear on the partner form.
4. Confirm required values, lookups, calculations, document templates, and messages with representative partner data.
5. Test missing, invalid, and corrected values before allowing production submissions.

A display condition changes presentation. It is not a substitute for permissions, query scope, endpoint authorisation, or removing sensitive fields from an integration response.

Test the portal workflow

Use a controlled environment and two intermediary records so that the negative scope check is meaningful.

1. Sign in as a user affiliated with the first intermediary.
2. Open New Application, select the intended product, and create an application with non-sensitive test data.
3. Save and submit the application using the configured workflow.
4. As an internal user, open the application and confirm that Seller and Submitter identify the first intermediary.
5. Request clarification, reject, or approve according to the test case. Use Lend only when the test is authorised to create a loan.
6. Return as the partner user and confirm the application and its current status in the Partner query.
7. Confirm that an application submitted for the second intermediary is absent from the list, global search, embedded lists, direct links, and export.
8. Confirm that internal decision, lending, loan, payment, configuration, and user-administration controls remain unavailable to the partner role.

Stop the rollout if the application has no Submitter, an out-of-scope application is visible, a direct link opens an unrelated application, or the role can reach an unapproved operation. Correct the affiliation, group, query, or record permissions before retrying.

Add an external-system channel

Use this section only when a separate partner system must submit applications or receive status updates.

1. Define the request fields, attachments, product mapping, validation errors, correlation identifier, and accepted response before implementation.
2. Give each intermediary its own authentication secret and dedicated affiliated API identity. Store secrets in approved secret or integration configuration, not an ordinary displayed field.
3. In the adapter, derive the Finsaku identity and affiliation from the authenticated partner configuration. Do not accept the intermediary identity from an untrusted request field.
4. Map the validated request to the borrower, terms, product, and application fields. Set or preserve the intermediary as Seller and Submitter.
5. Return a stable application reference and record the external correlation identifier in an approved tenant-defined field.
6. For status delivery, implement adapter callbacks or configure a Finsaku webhook event action for the required inquiry, rejection, and approval events.
7. Set request timeouts and retry rules. Make both submission and callback processing recognise the same correlation or event more than once without creating a duplicate business result.
8. Reconcile adapter logs, event-action Execution History, and Finsaku application history during support investigation.

Test a valid request, invalid credentials, validation failure, unknown product, attachment failure, repeated submission, callback timeout, repeated callback, and each supported decision outcome. After an uncertain submission response, search for the correlation identifier before retrying.

Verify the result

• The partner can create and submit only the intended product and fields.
• New partner applications carry the correct Seller and Submitter.
• The Partner query contains an in-scope application and excludes another intermediary's application.
• Global search, embedded lists, direct links, and export follow the same approved boundary.
• Internal review can process the application, while the partner cannot approve, lend, service a loan, or administer the tenant unless explicitly authorised.
• Application history identifies the acting portal or API user and the recorded status changes.
• For an external channel, one accepted submission creates one application and each supported outcome reaches the correct callback destination once at the business level.

Troubleshooting

Symptom	Check
Partner list is empty	User status, intermediary affiliation, active group, List Partner Queries, query Visibility, product access, and application Submitter.
Partner sees applications from another intermediary	Effective List Internal Queries permission, other group memberships, Query Object, Submitter values, other queries, direct-record permissions, and export configuration.
New application has the wrong intermediary	Signed-in user's current affiliation or the API identity and adapter mapping. Do not repair the list condition to match incorrect source data.
Partner can review but cannot save or submit	Exact application operation permission, record status, mandatory fields, active product version, and decision prerequisites.
Partner can see loans or payments unexpectedly	Loan and payment permissions, saved queries, direct-record access, embedded views, and every cumulative group membership.
Callback is missing	Application event, event-action condition and status, endpoint response, adapter logs, timeout, and Execution History.
Submission response was lost	Search by external correlation identifier and application reference before retrying.

Use Intermediaries and affiliations for organisation and user maintenance, Permission groups for role design, Saved queries for list configuration, and Event actions for webhook setup and execution history.