Merchant Onboarding

Merchant onboarding is the process of preparing a merchant to process payments through a fintech connection. This guide explains the complete journey from creating a merchant record to processing live transactions.

What is Onboarding?

When a merchant joins your platform and needs to process payments, they must be onboarded to one or more fintech connections (payment processors). Onboarding involves:

1. Creating the merchant record in Preczn
2. Collecting required business data and documentation
3. Submitting to the connection for underwriting review
4. Tracking approval status until the connection reaches Active

Preczn simplifies this process by normalizing data requirements across processors, tracking what's needed versus what's collected, and providing multiple methods to gather merchant information.

The Onboarding Journey

flowchart LR
    A[Create Merchant] --> B[Understand Requirements]
    B --> C[Collect Data]
    C --> D[Submit for Underwriting]
    D --> E[Track Status]
    E --> F[Ready to Process]

    style A fill:#29b6f6,color:#000
    style F fill:#66bb6a,color:#000

Step 1: Create the Merchant

Create a merchant record in Preczn using any of these methods:

At this stage, the merchant exists in Preczn but cannot process payments. Each merchant receives a unique ID with the mid_ prefix (e.g., mid_01abc123def456).

📘

Note

Creating a merchant does not automatically start the onboarding process. Merchants remain in a holding state until you explicitly initiate onboarding to a connection.

Step 2: Understand Requirements

Each connection has specific data requirements for underwriting. These vary by processor and may include:

Preczn tracks what's required for each connection and what data you've already collected. Check requirements using:

• API: Get Merchant Requirements endpoint returns required fields, existing data, and missing items
• Dashboard: Merchant Vault shows missing requirement counts with detailed breakdowns
• Webhooks: Merchant events include connection statuses and missing data lists

Step 3: Collect Merchant Data

You have two primary approaches for gathering the required information:

Option A: Boarding Forms (Recommended for Sensitive Data)

Boarding forms are Preczn-hosted web forms that collect merchant data directly—without sensitive information touching your servers.

When to use boarding forms:

• You don't want to handle merchant banking information
• Merchants should complete their own applications
• You need a quick implementation without building forms

How it works:

1. Generate a boarding form link via API
2. Send the link to your merchant
3. Merchant completes the form on a Preczn-hosted page
4. Data is stored securely and associated with the merchant record

Option B: API Data Submission

Submit merchant data programmatically through the Merchant API.

When to use API submission:

• You already collect merchant data in your application
• You need full control over the user experience
• You're automating merchant onboarding at scale

How it works:

1. Collect data through your own forms or systems
2. Submit to Preczn via API calls
3. Preczn validates and stores the data

Option C: Hybrid Approach

Combine both methods—use your existing systems for data you already collect, then generate a boarding form to capture remaining items like banking details or document uploads.

Step 4: Submit for Underwriting

Preczn continuously evaluates merchant data against connection requirements. When all required data is collected, the connection status automatically changes from Requirements to Ready, indicating the merchant is eligible for submission.

When you initiate onboarding (via API call, dashboard action, or automatic submission), Preczn:

1. Transforms your normalized merchant data into the connection's required format
2. Transmits the data to the processor's onboarding system
3. Tracks the submission status in a standardized format

Manual vs. Automatic Submission

By default, submission requires an explicit API call or dashboard action—this gives you control over timing and allows batch submissions.

However, you can enable automatic submission by setting autoTransmitMerchantData: true on your boarding form template. When enabled, Preczn automatically submits the merchant to the connection as soon as the form is completed and all requirements are satisfied.

Step 5: Track Status

Monitor onboarding progress through the Dashboard, API, or webhooks. Preczn normalizes status across all processors into a unified set of statuses.

Connection Status Reference

📘

Additional Statuses

Some connections may use additional statuses such as Evaluating, Inquiry, Pending, or PartialBoarded for processor-specific workflow states. These appear in the same status field on the connection object.

Webhook Events

Subscribe to merchant webhooks to receive real-time status updates. When a merchant's connection status changes, Preczn sends a merchant.updated webhook containing the full merchant record:

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

The connections array includes each connection's current status and missingRequiredData fields, allowing you to track onboarding progress programmatically.

Ready to Process

Once a connection reaches Active status, the merchant can immediately process payments through that connection. Merchants are active by default (active: true), so no additional enablement step is required.

📘

Plans

Merchants must have a plan assigned to process transactions. Plans determine routing rules, fees, and other processing configurations. You can assign plans at any point during or after onboarding.

📘

Operational Control

If you need to temporarily prevent a merchant from processing (for compliance review, go-live timing, etc.), you can set active: false on the merchant record. This is optional and used for operational control—not a required onboarding step.

Choosing Your Approach

Common Patterns

📘

Implementation Requirement

All patterns require your system to store the Preczn merchant ID. Patterns using boarding forms also require tracking which form template to use. Plan your data model accordingly.

📘

Best Practice

Regardless of which pattern you use, create the merchant record with whatever data you already have. Preczn will track which fields are still needed—there's no need to wait until you have complete information.

Self-Service Merchant Onboarding

For platforms where merchants sign up and complete their own applications:

1. Merchant signs up on your platform
2. Your system creates the merchant record via API (with plan assigned)
3. Generate a boarding form link and redirect the merchant to complete it
4. Merchant completes the form on the Preczn-hosted page
5. Upon completion, merchant is redirected back to your application via the configured returnUrl
6. Webhook notifies you when requirements are met
7. Your system submits for underwriting (or use autoTransmitMerchantData for automatic submission)
8. Webhook notifies you when connection reaches Active
9. Merchant is ready to process payments

Operator-Assisted Onboarding

For platforms where operators manage onboarding through a CRM or back-office system:

1. Merchant signs up on your platform
2. Your system automatically creates the merchant record in Preczn via API
3. Operator reviews the merchant in their CRM (e.g., Salesforce) and triggers boarding form creation
4. Boarding form link is emailed to the merchant
5. Merchant completes the form at their convenience
6. Webhook notifies your system when requirements are met
7. Operator or automated workflow submits for underwriting
8. Webhook notifies you when connection reaches Active
9. Merchant is ready to process payments

Platform-Controlled Onboarding

For platforms that want full control over the merchant onboarding experience:

1. Merchant signs up on your platform
2. Your system creates the merchant record via API (with plan assigned)
3. Query the requirements endpoint to determine which fields are needed
4. Display your own forms to collect the required data
5. Submit collected data to Preczn via API as the merchant progresses
6. Re-query requirements to update your UI with remaining fields
7. When all requirements are met, submit for underwriting via API
8. Poll status or receive webhook when connection reaches Active
9. Merchant is ready to process payments

This approach gives you maximum UI/UX control—you design the entire merchant experience while Preczn handles data validation, transformation, and processor communication.