Onboarding Troubleshooting

This guide helps you diagnose and resolve common issues that occur during merchant onboarding. For an overview of the onboarding process, see Merchant Onboarding.

Status-Specific Issues

Each connection status indicates where the merchant is in the onboarding journey. When a merchant appears stuck, use the status to guide your troubleshooting.

Stuck in "Requirements"

The Requirements status means one or more required fields are missing. This is the most common pre-submission issue.

How to identify missing fields:

Via API:

GET /v1/merchants/:merchantId/requirement

The response includes a missingRequiredData array for each connection:

{
  "connections": [
    {
      "processor": "Payrix",
      "status": "Requirements",
      "missingRequiredData": [
        "owners[0].ssn",
        "owners[0].dob",
        "banking[0].routing",
        "banking[0].account"
      ]
    }
  ]
}

Via Dashboard:

1. Navigate to Merchants → select the merchant
2. View the Merchant Vault panel
3. Each section shows a count of missing requirements in parentheses
4. Click into each connection tab to see the specific missing fields

Common missing fields by category:

Resolution steps:

1. Query the requirements endpoint to get the exact missing fields
2. Collect the missing data from the merchant
3. Submit via API or have the merchant complete a boarding form
4. Re-query requirements to confirm all fields are satisfied
5. Status will automatically transition to Ready when complete

See Onboarding Data Requirements for detailed field path explanations.

Stuck in "Ready" After Form Completion

A common question: "The merchant completed the form, but the connection is still in Ready status—why wasn't the merchant onboarded?"

This is typically caused by one of two issues:

1. Auto-transmit is not enabled

The form template does not have autoTransmitMerchantData set to true. Without this setting, completing a boarding form only collects and saves the merchant data—it does not automatically initiate onboarding.

Solution: Either enable autoTransmitMerchantData on the form template for future forms, or manually initiate onboarding:

• Via Dashboard (most common): Navigate to the merchant, select the connection, and click the onboard action
• Via API: POST /v1/merchants/:merchantId/connections/:connectionId/onboard

2. The merchant didn't submit the form

The autoTransmitMerchantData feature is only triggered when the merchant clicks Submit on the final page of the form. It's possible the merchant completed all the required fields but then abandoned the form without submitting.

How to verify:

• Check the form status via API: GET /v1/merchants/:merchantId/forms
• A form with status: completed was submitted; a form with status: pending or status: expired was not

Solution: If the merchant data appears complete and the connection is Ready, the platform can choose to initiate onboarding manually via Dashboard or API.

⚠️

Abandoned Forms

Preczn does not automatically onboard merchants who fill out form fields but don't submit. There is no way to distinguish between a merchant who abandoned the form versus one who intentionally chose not to submit. If the platform wants to proceed with onboarding, it is their decision to initiate manually.

Stuck in "Queued" or "Sent"

These statuses indicate the onboarding request has been submitted but the processor hasn't responded yet.

Normal processing times:

Processing times vary by connection and can range from minutes to several business days depending on the processor's review queue.

What to check:

1. Verify submission completed - Confirm the onboard API call returned a success response
2. Check for silent failures - Some processors may not send status updates for all failure modes
3. Review webhook delivery - Ensure your webhook endpoint is receiving events

When to escalate:

• Queued for more than 1 hour: May indicate a Preczn processing issue—contact support
• Sent for more than 3 business days: May need processor escalation—contact support with the merchant ID and connection

📘

Webhook Monitoring

Subscribe to merchant.updated webhooks to receive real-time status updates. If you're not receiving updates, check your webhook configuration and endpoint health.

RFI (Request for Information)

The RFI status means the processor is requesting additional information before completing underwriting.

Finding RFI details:

RFI requests typically arrive through:

• Processor-specific portals
• Email notifications from the processor
• Dashboard notifications (when available)

Common RFI types:

Resolution steps:

1. Identify what information the processor is requesting
2. Collect the required information or documentation
3. Submit the information:
   • For data updates: Use the appropriate PATCH endpoint
   • For documents: Use the Add Attachment endpoint
4. Re-initiate onboarding:
   • Via Dashboard (most common): Navigate to the merchant, select the connection, and click the onboard action
   • Via API: POST /v1/merchants/:merchantId/connections/:connectionId/onboard
5. Monitor for status change via webhooks or polling

📘

RFI Response Window

Processors may have time limits for RFI responses. Respond promptly to avoid application expiration.

Error Status

The Error status indicates the processor returned an error during the onboarding process. This error originates from the connection you're attempting to board to—not from Preczn.

Retrieving the error:

The error message is available via the connections API:

GET /v1/merchants/:merchantId

Check the connection object for error details. Note that error messages are often programmatic in nature (processor-specific codes or technical messages) and may require interpretation.

Common error causes:

Resolution steps:

1. Retrieve the error message from the connection object via API or Dashboard
2. Thoroughly review the error for clues on how to remediate—look for field names, validation messages, or error codes
3. Correct the underlying issue if identifiable:
   • For data issues: Update the merchant record with corrected values
   • For credential issues: Verify connection configuration in Command Center
   • For processor issues: Wait and retry
4. Re-initiate onboarding after making corrections:
   • Via Dashboard (most common): Navigate to the merchant, select the connection, and click the onboard action
   • Via API: POST /v1/merchants/:merchantId/connections/:connectionId/onboard

📘

Error Recovery

The onboard endpoint accepts connections in Error status, allowing you to retry after resolving the underlying issue.

When you can't resolve the error:

If the error message is unclear or you cannot determine the cause, contact Preczn support with the merchant ID, connection ID, and the exact error message. Preczn will investigate the error and work to implement a solution to prevent the issue for future merchants.

⚠️

Note

Remediations may take time to implement and some processor-specific errors may require manual resolution or coordination with the processor directly.

Rejected Applications

The Rejected status means the processor has declined the merchant application.

Understanding rejection reasons:

Rejection reasons vary by processor and may include:

• High-risk business type or industry
• Negative credit history
• Incomplete or inconsistent information
• Failed identity verification
• Prohibited business activity

Which rejections are correctable?

Resolution steps:

1. Review the rejection reason (available in Dashboard or via processor communication)
2. If correctable:
   • Update the merchant data to address the issue
   • Re-initiate onboarding to resubmit
3. If not correctable:
   • Consider alternative processors
   • Contact the processor for appeal options (if available)

📘

Processor Appeals

Some processors offer appeal processes for rejected applications. Contact your processor representative for specific appeal procedures.

Unconfigured Status

The Unconfigured status indicates the connection lacks valid credentials—this is a configuration issue, not a data issue.

Resolution:

1. Navigate to Command Center → Connections
2. Select the connection
3. Verify credentials are entered and valid
4. If credentials are correct, test the connection
5. Once configured, the status will change to Requirements or Ready

Data Issues

Validation Errors on Submission

If the onboard endpoint returns a 400 error, the request failed validation.

Example error response:

{
  "statusCode": 400,
  "message": "The connection must have a status of 'Ready', 'RFI' or 'Error' in order to initiate onboarding.",
  "error": "Bad Request"
}

Common validation failures:

Field format requirements:

See Onboarding API Reference for complete field specifications.

Data Not Appearing After Form Completion

If merchant data doesn't appear after a boarding form is completed:

Check these items:

1. Form status - Verify the form was actually completed (not abandoned)

   Bash

   GET /v1/merchants/:merchantId/forms

   Check for forms with status: completed

2. Webhook delivery - Confirm your webhook endpoint received the form.completed event

3. Merchant record - Query the merchant directly to see if data was saved:

   Bash

   GET /v1/merchants/:merchantId

4. Form expiration - Forms expire after the configured duration. If expired, generate a new form link

Resolution:

• If form shows incomplete: Merchant needs to finish the form
• If form expired: Generate a new form link
• If data is present but requirements not satisfied: Check missingRequiredData for remaining fields

Webhook Delivery Issues

If you're not receiving expected webhooks:

Troubleshooting steps:

1. Verify endpoint configuration - Check webhook URL in Command Center
2. Test endpoint accessibility - Ensure endpoint is publicly accessible and returns 2xx
3. Check endpoint health - Review your server logs for incoming requests
4. Verify event subscription - Confirm you're subscribed to merchant.updated events

Manual status check:

If webhooks aren't working, poll the merchant endpoint:

GET /v1/merchants/:merchantId

The response includes current connection statuses and missingRequiredData arrays.

Quick Reference

Getting Help

If you've followed this guide and still can't resolve the issue:

1. Gather information:

   • Merchant ID (mid_...)
   • Connection ID (midCon_...)
   • Current status
   • Error messages (if any)
   • Timestamp of when issue started

2. Contact support with the above details for assistance

Related Pages

• Merchant Onboarding - Complete onboarding journey overview
• Onboarding Data Requirements - Understanding requirements and field paths
• Onboarding API Reference - API endpoints for programmatic onboarding
• Boarding Forms - Preczn-hosted data collection