Creating Forms

This guide explains how to generate boarding form links for merchants and configure automatic onboarding behavior. Boarding forms can be created from the Preczn dashboard or programmatically through the API, and a single form can onboard a merchant to one fintech connection or to several at the same time.

Choosing a Method

Both methods produce the same form at the same kind of URL. The difference is who triggers creation, and when.

Most platforms use both: the dashboard while integrating and for exceptions, the API for everything in steady state.

Prerequisites

Before generating form links, you need:

1. A configured domain — a branded subdomain that boarding form URLs will live under. See Configuring Domain Names.
2. A form template — defines styling, return URLs, expiration, and any custom form fields. See Boarding Form Templates.
3. A merchant record — the merchant who will complete the form.
4. One or more fintech connections, already added to the merchant — the connection or connections the merchant will be onboarded to. Form creation resolves against the connections already on the merchant record; it does not add them.

Generating Form Links

Via Dashboard

1. Navigate to the merchant detail page.
2. Select the Forms tab.
3. Click Create New Form.
4. Select the connection (or connections) and the form template.
5. Click Get URL to copy the link.

Via API

Endpoint: POST /v1/forms

Minimum required fields:

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionId": "Payrix",
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh"
}

To onboard the merchant to multiple connections from a single form, pass connectionIds (plural) instead of connectionId:

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionIds": ["Payrix", "Greensky"],
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh"
}

📘

Connection names vs. connection IDs

For both connectionId and entries in connectionIds, you can provide either the connection name (Payrix, Greensky, AdyenForPlatforms, etc.) or the connection ID (midCon_...). We recommend using connection names — they're easier to read, easier to copy from a list of supported connections, and don't require you to look up the connection ID for the specific merchant first. Preczn resolves connection names to the matching connection on the merchant.

📘

Single-connection vs. multi-connection

A request must include exactly one of connectionId or connectionIds — sending both, or neither, returns 400 Bad Request. Multi-connection forms are KYC only. See Multi-Connection Boarding Forms for the full feature guide.

With overrides:

Any field on the form template can be overridden per form by including it in the request body. Common overrides include expirationInHours, returnUrl, and autoTransmitMerchantData:

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionId": "Payrix",
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh",
  "expirationInHours": 72,
  "returnUrl": "https://yourplatform.com/merchant/mid_1sxmscs49g95t8y6n79nt922xr/complete"
}

Response:

{
  "id": "form_5mno6pqr7stu8vwx",
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "processorName": "Payrix",
  "url": "https://boarding.yourplatform.com/form_5mno6pqr7stu8vwx/AcmeCorp",
  "expiresOn": "2026-05-07T10:30:00Z"
}

For multi-connection forms, the response returns connectionIds and processorNames (plural) instead of their singular counterparts. The full response also carries every other field on the form (template overrides, expiration, styling, etc.) — the snippet above shows only the fields most commonly used to send the form to the merchant.

You send the url to the merchant the same way you would for any other boarding form.

Starting Boarding From Your Own Application

The common production shape is an action inside your own product that starts a merchant on a service — setting up card processing, applying for financing, enabling payouts. When the merchant takes that action, your backend creates the form and sends them straight into it; nobody copies a link by hand.

1. The merchant takes the action in your application.
2. Your backend confirms the merchant exists in Preczn and already has the connection you're boarding them to. If not, create the merchant and add the connection first — see Creating Merchants.
3. Your backend calls POST /v1/forms with the merchant, the connection, and your form template, then reads url from the response.
4. Your application redirects the merchant to url. Redirect rather than storing or emailing it — anyone holding a non-expired form URL can view and submit that merchant's boarding data, so keep expirationInHours as short as your flow allows.
5. The merchant completes the form and lands on the returnUrl. Point that back at your own application so they return to where they started.

🚧

The connection must already exist on the merchant

POST /v1/forms resolves connectionId (or each entry in connectionIds) against the connections already on the merchant record. If the merchant has no matching connection, the request returns 404 Not Found — Connection not found!. Add the connection to the merchant before creating the form.

📘

Send an idempotency key

POST /v1/forms accepts an optional idempotency-key header. Send a unique value per user action — a UUID works well — and a repeat of the same key returns the original response for 24 hours instead of minting a second form link. This keeps a double-click, a retry, or a network timeout from generating duplicate forms.

Offering a Catalogue of Services

If your product lets merchants choose which services they want — card processing, financing, payouts — you can build the connection list from that selection at request time and create a single multi-connection form covering exactly what they picked. The catalogue lives in your application; the form adapts to it.

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionIds": ["Payrix", "Greensky"],
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh"
}

Standard requirement fields need no work on your side. Preczn computes the combined requirement set for whichever connections are on the form and requests a field if any of them needs it, so a merchant who picks two services still fills out one set of business, ownership, and banking information — and Preczn reports what's still missing for each connection as they go.

🚧

Custom form fields come from the template, not the connections

Standard requirement fields combine automatically across the form's connections. Custom form fields do not — they're inherited from the form template you reference, so the template has to cover every connection on the form.

That leaves two ways to handle a catalogue that can produce many different combinations:

• One broad template. Include every custom field your catalogue could need and reference the same formTemplateId every time. Simplest to run, at the cost of a merchant occasionally seeing a custom field that only matters to a service they didn't pick.
• A template per combination. Each form shows only the custom fields relevant to the services chosen. Leaner for the merchant, but you maintain a template for every combination plus a mapping from selection to formTemplateId.

Start with the broad template unless the extra fields are genuinely confusing — Preczn already narrows the standard fields for you, so the difference is limited to your custom ones. See Multi-Connection Boarding Forms for the full feature guide.

Automatic Onboarding

Enabling Auto-Transmit

Set autoTransmitMerchantData: true on the form template (or override it on a single form) to automatically initiate onboarding when the merchant submits the form, provided all requirements are satisfied.

For a multi-connection form, auto-transmit triggers boarding for every connection on the form — not just one. Each connection is onboarded sequentially in the background after submission.

Manual Onboarding

When auto-transmit is disabled (the default), boarding must be initiated explicitly. From the dashboard, navigate to the connection on the merchant and click Onboard. From the API:

POST /v1/merchants/:merchantId/connections/:connectionId/onboard

For multi-connection forms, you initiate onboarding per connection.

What Happens After Submission

1. The merchant's data is saved to the merchant record (business info, ownership, banking, attachments).
2. Connection requirements are re-evaluated.
3. Connection status updates to Ready (manual onboarding) or Queued (auto-transmit).
4. The merchant is redirected to the form's returnUrl.

📘

No dedicated webhook fires when a form is submitted

To detect form completion, poll GET /v1/forms/:id and check the completionDate field, or subscribe to the connection-status webhooks that fire when each connection moves through the boarding lifecycle.