Creating Forms

This guide covers how to generate boarding form links for merchants and configure automatic onboarding behavior. For an overview of what boarding forms are and when to use them, see Boarding Forms.

Prerequisites

Before generating form links, you need:

1. A configured domain - Your branded subdomain for form URLs
2. A form template - Defines styling, return URLs, and expiration settings
3. A merchant record - The merchant who will complete the form
4. A connection - The processor connection the merchant is boarding to

Configure Your Domain

Set up a custom subdomain (e.g., boarding.yourdomain.com) so form URLs display your branding instead of a generic Preczn URL.

Example branded URL:

https://boarding.yourdomain.com/form_abc123/AcmeCorp

See Configuring Domain Names for DNS and SSL setup instructions.

Create a Form Template

Templates define the appearance and behavior of your forms—logo, colors, return URLs, expiration time, and terms of service options.

See Boarding Form Templates for template configuration. Key settings include:

• Branding - Logo, colors, header text
• Return URLs - Where to redirect after completion or expiration
• Expiration - How long form links remain valid (1 hour to 90 days)
• Auto-transmit - Whether to automatically initiate onboarding on submission

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 and template
5. Click Get URL on the created form to copy the link

Via API

POST /v1/forms

Minimum required fields:

{
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "formTemplateId": "formTemp_1abc2def3ghi4jkl"
}

With template overrides:

{
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "formTemplateId": "formTemp_1abc2def3ghi4jkl",
  "expirationInHours": 72,
  "returnUrl": "https://yourplatform.com/merchant/mid_123/complete"
}

The form inherits all settings from the template, but you can override any property for this specific form. See Boarding Forms API Reference for all available fields.

Response:

{
  "id": "form_5mno6pqr7stu8vwx",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "formUrl": "https://boarding.yourplatform.com/form_5mno6pqr7stu8vwx/AcmeCorp",
  "status": "pending",
  "expiresAt": "2024-01-17T10:30:00Z"
}

Send the formUrl to your merchant via email, in-app notification, SMS, or any other channel.

📘

Connection ID

You can provide either the connection ID (midCon_...) or the processor name (e.g., Payrix). If using a processor name, Preczn resolves it to the appropriate connection for that merchant.

Automatic Onboarding

By default, completing a boarding form only collects and saves data—it doesn't automatically submit the merchant for onboarding. You control when to initiate onboarding via Dashboard or API.

Enabling Auto-Transmit

To enable automatic submission, set autoTransmitMerchantData: true on your form template (or override it per-form). When enabled:

1. Merchant completes all form sections
2. Merchant clicks Submit on the final Review page
3. If all requirements are satisfied, Preczn automatically initiates onboarding
4. Connection status changes from Ready to Queued

⚠️

Submit Button Required

Auto-transmit only triggers when the merchant clicks Submit. Completing fields without submitting does not trigger onboarding.

Manual Onboarding

When autoTransmitMerchantData is false (the default):

• Completing the form saves data to the merchant record
• Connection status updates to Ready when all requirements are satisfied
• You initiate onboarding manually:
  • Via Dashboard: Navigate to the merchant, select the connection, click the onboard action
  • Via API: POST /v1/merchants/:merchantId/connections/:connectionId/onboard

This approach gives you control over when merchants are submitted—useful for review workflows or staged rollouts.

Tracking Form Completion

Check Form Status

Via API:

GET /v1/forms/merchant/:merchantId

Via Dashboard: View form status in the merchant's Forms tab.

Form Statuses

What Happens After Completion

When a merchant submits the form:

1. Data is saved to the merchant record
2. Requirements are re-evaluated for the connection
3. Connection status updates:
   • If requirements satisfied → Ready (or Queued if auto-transmit enabled)
   • If requirements still missing → Requirements
4. Merchant is redirected to the template's returnUrl

📘

No Form Completion Webhook

There is no dedicated webhook for form completion. To monitor form status, poll the forms API or check connection status changes via merchant.updated webhooks.

Troubleshooting

Form Completed but Status Still "Ready"

If auto-transmit is enabled but the merchant wasn't onboarded:

1. Merchant didn't click Submit - They may have completed fields but abandoned before submitting
2. Requirements not satisfied - The form may not have collected all required fields

Check form status via API to confirm completion. See Onboarding Troubleshooting for detailed diagnosis steps.

Form Expired

If a merchant's form expired:

1. Partially completed data is preserved on the merchant record
2. Generate a new form link—the merchant will see their previously entered data
3. Consider increasing expirationInHours for future forms if merchants need more time

Related Pages

• Boarding Forms - Overview and when to use boarding forms
• Boarding Form Templates - Template configuration and inheritance
• Boarding Forms API Reference - Complete API documentation
• Onboarding Troubleshooting - Diagnose form and onboarding issues