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.

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 — the connection or connections the merchant will be onboarded to.

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.

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.