Onboarding Data Requirements

Every payment processor requires specific merchant data to complete underwriting. Preczn normalizes these requirements across all connections, tracks what data you've collected, and tells you exactly what's still needed.

How Requirements Work

Preczn maintains the requirements library for each supported processor. You don't need to tell Preczn what fields Adyen, Stripe, Payrix, or other processors require—Preczn already knows. When you add a connection to a merchant, Preczn automatically applies the correct requirements template and continuously compares the merchant's data against it, reporting any gaps.

📘

Who Maintains Requirements?

Preczn maintains the KYC/KYB field requirements for each processor. These are built into the platform based on each processor's onboarding specifications. You are not responsible for defining or passing requirements—simply collect merchant data, and Preczn tells you what's missing for each connection.

flowchart LR
    A[Merchant Data] --> B{Requirements Engine}
    C[Processor Template] --> B
    B --> D[Missing Requirements]
    D --> E[Connection Status]

    style B fill:#29b6f6,color:#000
    style E fill:#66bb6a,color:#000

This evaluation happens automatically whenever merchant data changes. You don't need to manually trigger requirement checks—Preczn keeps the missingRequiredData list and connection status up to date in real time.

Requirement Categories

Preczn organizes required data into four categories:

Different processors require different subsets of these fields. For example, one processor might require full SSN while another only needs the last four digits.

📘

Attachments

Preczn supports file attachments (business license, articles of incorporation, etc.) for onboarding and RFI responses, but attachments are not tracked as requirements. They won't appear in missingRequiredData or affect connection status transitions.

Checking Requirements

Via API

The Get Merchant Requirement endpoint returns the merchant record with requirement details for each connection:

GET /v1/merchants/:merchantId/requirement

Response:

{
  "id": "mid_01abc123def456",
  "name": "Acme Corp",
  "legalName": "Acme Corporation LLC",
  "address": { ... },
  "tin": "****6789",
  "connections": [
    {
      "id": "midCon_6v59stftbs837axmpahj21m8jf",
      "processor": "Payrix",
      "status": "Requirements",
      "missingRequiredData": [
        "owners[0].ssn",
        "owners[0].dob",
        "banking[0].routing",
        "banking[0].account",
        "connectionspecificRequirements.tosDate"
      ]
    }
  ]
}

The missingRequiredData array contains field paths indicating exactly which data points are still needed. Field paths use dot notation and array indices to identify specific fields:

Via Dashboard

The Dashboard provides visual requirement tracking in two places:

Merchant Vault: Each section displays a count of missing requirements in parentheses:

• Business Information (3)
• Owners (2)
• Banking (2)
• Attachments (0)

Connection Tabs: Each processor tab shows its missing count, and selecting a processor displays a detailed breakdown of exactly which fields are needed.

When all requirements are met for a connection, the section displays a green checkmark instead of a count.

Via Webhooks

When merchant data changes, Preczn sends a merchant.updated webhook that includes the current connection statuses and missing requirements:

{
  "event": "merchant.updated",
  "data": {
    "id": "mid_01abc123def456",
    "connections": [
      {
        "id": "midCon_6v59stftbs837axmpahj21m8jf",
        "processor": "Payrix",
        "status": "Ready",
        "missingRequiredData": []
      }
    ]
  }
}

Subscribe to merchant webhooks to receive real-time updates as requirements are satisfied.

Connection Status and Requirements

The connection status reflects requirement completion:

When a merchant's data changes and all requirements for a connection become satisfied, Preczn automatically transitions the connection from Requirements to Ready. This transition triggers a merchant.updated webhook.

📘

Automatic Status Transitions

Preczn only evaluates requirements for connections in Unconfigured, Requirements, or similar pre-submission states. Once a connection is submitted (status Queued, Sent, Underwriting, etc.) or active, the requirements check no longer affects the status.

Custom Requirement Templates

While Preczn maintains default requirements for each processor, some platforms need different requirements for the same connection based on merchant characteristics—for example, different fields for government entities versus LLCs.

Preczn supports this through custom requirement templates:

1. Contact Preczn Support to configure additional requirement templates for a connection with your specific field requirements
2. Assign the template to a merchant's connection before collecting data via the Update Connection Details endpoint:
   Bash

   PATCH /v1/merchants/:merchantId/connections/:connectionId
   {
     "requirementsTemplate": "reqTemp_exd4sjvk483zrz7e4anyh12kr"
   }

3. Collect data via boarding forms or API—Preczn evaluates against the assigned template

If no custom template is assigned, Preczn uses the default template for that processor, which applies to all merchant types.

📘

When to Assign Templates

Assign the custom requirement template before generating a boarding form or displaying your own data collection UI. This ensures Preczn evaluates the correct requirements from the start.

Processor Variations

Each processor has unique requirements. Some real-world variations:

Requirements are binary—each field is either required or not for a given processor. Preczn abstracts these differences by normalizing the data model. You collect data into Preczn's standard fields, and Preczn handles the processor-specific mapping and validation.

Best Practices

Collect Data Incrementally

You don't need to gather all requirements before creating a merchant. Create the merchant with whatever data you have, then add more data over time. Preczn tracks progress automatically.

1. Create merchant with basic business info
2. Query requirements → see what's still needed
3. Collect additional data (owners, banking)
4. Query requirements → fewer items missing
5. Repeat until missingRequiredData is empty

Use the Requirements Endpoint to Build Forms

If you're building your own onboarding UI, use the requirements endpoint to dynamically determine which fields to display:

1. Fetch the merchant with requirements
2. Parse the missingRequiredData array
3. Display form fields only for missing items
4. Submit collected data via API
5. Re-fetch to update your UI

This approach ensures you only ask merchants for information that's actually needed.

Handle Multiple Connections

A merchant may have multiple connections with different requirements. The missingRequiredData array is specific to each connection in the connections array. A field might be required for one processor but not another.

When building UIs, consider showing:

• A unified view of all missing fields across all connections
• Per-processor views showing only that processor's requirements
• Progress indicators per connection

Related Pages

• Merchant Onboarding - Complete onboarding journey overview
• Boarding Forms - Preczn-hosted forms for data collection
• Create Merchant API - API reference for merchant creation
• Webhooks - Subscribe to merchant update events