Create Signature Link

post

https://sandbox.finmid.com/api/v1/capital/businesses/{business_id}/offers/{offer_group_id}/signature-link

Returns a link that opens finmid's signature screen for one Offer. Use it when your platform shows the Offers in its own UI.

The Business always accepts an Offer in finmid's iframe. With this link the iframe skips the offer overview and opens a single screen to accept the Offer you pass in offer_id. The screen does not repeat the terms of the Offer, so show them in your UI. It asks for the use of funds when you do not send them.

The flow

When you show the Offers to the Business, fetch them with Get Active Offer Group without suppress_offer_opened_event=true. With your own UI, that call is what records that the Business opened the Offers: the first such call for an Offer Group triggers capital_offer.opened.
When the Business picks an Offer in your UI, call this endpoint with the offer_group_id and the offer_id of that Offer.
Open the returned url in an iframe or in a mobile webview before valid_until.
When the Business accepts the Offer, the iframe sends the message { "type": "OFFER_ACCEPTED" }. finmid sends it with window.parent.postMessage to the origin configured for your platform (contact finmid to configure it), and in mobile webviews through window.finmidBridge (Android) and window.webkit.messageHandlers.finmidBridge (iOS). finmid then sends capital_offer.accepted.

Neither calling this endpoint nor opening the returned url counts as the Business opening the Offers: neither triggers capital_offer.opened.

Every call returns a new link. A link can stop working before its valid_until, for example when finmid replaces the Offer Group: fetch the current Offer Group with Get Active Offer Group and call this endpoint again.

Errors

Status	`code`	When	What to do
`400`	`validation_error`	`offer_id` is missing, a value of `use_of_funds` is not one of the listed ones, `use_of_funds` contains `OTHER` without `use_of_funds_comment`, `use_of_funds_comment` is longer than 500 characters, or `offer_group_id` is not a UUID.	Fix the request.
`401`		The API key is missing or invalid.	Check the `X-API-Key` header.
`404`	`business_not_found`	No Business with this `business_id` exists on your platform.	Check the `business_id`.
`404`	`offer_group_not_found`	The Business has no Offer Group with this `offer_group_id`.	Use the `id` of the Offer Group returned by Get Active Offer Group.
`404`	`offer_not_found`	The Offer Group has no Offer with this `offer_id`.	Use an `id` from `flexible_offers` or `fixed_offers` of the same Offer Group.
`409`	`business_details_incomplete`	The Business has no valid bank account number or phone number. In the same case Get current Offer returns no `embedding_link` URL.	Complete the bank account and the phone number of the Business.
`409`	`offer_group_not_active`	The Offer Group has expired, was replaced by a new Offer Group, was withdrawn, or the Business already accepted one of its Offers.	Fetch the current Offer Group with Get Active Offer Group.
`500`	`server_error`	An unexpected error occurred.	Retry later.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

business_id

string

required

length ≤ 100

^[a-zA-Z0-9_\.\-]{1,100}$

Identifier of the Business.

offer_group_id

uuid

required

Identifier of the Offer Group, as received in capital_offer.created.

Body Params

offer_id

uuid

required

Identifier of the Offer the Business picked in your UI. Use an id from flexible_offers or fixed_offers of the Offer Group returned by Get Active Offer Group.

use_of_funds

array of strings, unique

What the Business will use the Funding for, when you ask the Business in your UI.

If you send at least one value, the signature screen does not ask the Business for the use of funds.
If you send none, the signature screen asks the Business. For the CSP financing setup the Business has to choose at least one before accepting.

Values:

NEW_EQUIPMENT: new equipment.
RENOVATIONS: renovations.
NEW_VENUE: a new venue.
MARKETING: marketing.
BILLS: bills.
OTHER: another use, described in use_of_funds_comment.

use_of_funds_comment

string | null

Describes the OTHER use of funds, up to 500 characters. Required, and not blank, when use_of_funds contains OTHER. Without OTHER it is left out of the link, but a comment longer than 500 characters still answers 400 validation_error.

auth_context

string

enum

Overrides the default finmid two-factor authentication (2FA) policy for a single embedding session.

Honored only when finmid has enabled this capability for your platform; otherwise it is ignored and the platform's default 2FA policy applies.

The chosen policy applies to the entire embedding session, which means that both (1) offer acceptance and (2) the merchant dashboard are gated by the same 2FA decision.

VERIFIED: the platform has already strongly authenticated the user for this session, so finmid's 2FA is skipped.
UNTRUSTED: the session is weakly authenticated (e.g. a shared device or shared login), so finmid enforces 2FA using the method it has configured for your platform (e.g. SMS).

Allowed:

Responses

401

Missing or invalid API key. Could not authenticate API request.

200Link to the signature screen of the Offer.

400Validation error. No link is created.

404The Business, its Offer Group, or the Offer does not exist.

409The Business cannot accept an Offer of this Offer Group.

500An unexpected server error occurred. You should try again later or contact finmid support.