Onboarding API Reference

This reference covers the API endpoints used to onboard merchants programmatically. For a conceptual overview, see Merchant Onboarding.

Onboarding Workflow via API

A typical API-driven onboarding flow. You don't need to collect all data upfront—Preczn tracks what's still needed for each processor connection. See Onboarding Data Requirements to understand how requirements are evaluated.

1. Create merchant          POST /v1/merchants
2. Add owners               POST /v1/merchants/:id/owners
3. Add bank account         POST /v1/merchants/:id/bankaccounts
4. Update connection data   PATCH /v1/merchants/:id/connections/:connectionId
5. Check requirements       GET /v1/merchants/:id/requirement
6. Initiate onboarding      POST /v1/merchants/:id/connections/:connectionId/onboard

Create Merchant

Creates a new merchant record. Include as much data as you have—Preczn tracks what's still needed.

POST /v1/merchants

Request Body:

{
  "name": "Acme Corp",
  "legalName": "Acme Corporation LLC",
  "email": "[email protected]",
  "phone": "15551234567",
  "tin": "123456789",
  "businessType": "llc",
  "mcc": "5999",
  "website": "https://acme.com",
  "address": {
    "address1": "123 Main St",
    "city": "Austin",
    "region": "TX",
    "postal": "78701",
    "country": "USA"
  },
  "connections": [
    {
      "processor": "Payrix"
    }
  ]
}

📘

Field Structure

Business information fields are at the root level of the merchant object, not nested under a businessInfo wrapper. Phone numbers use E.164 format without separators (e.g., 15551234567). Country codes use ISO 3166-1 alpha-3 format (e.g., USA).

Response:

{
  "id": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "name": "Acme Corp",
  "legalName": "Acme Corporation LLC",
  "active": true,
  "email": "[email protected]",
  "phone": "15551234567",
  "tin": "****6789",
  "businessType": "llc",
  "mcc": "5999",
  "website": "https://acme.com",
  "address": { ... },
  "connections": [
    {
      "id": "midCon_6v59stftbs837axmpahj21m8jf",
      "processor": "Payrix",
      "status": "Requirements",
      "missingRequiredData": ["owners[0].firstName", "owners[0].lastName", ...]
    }
  ]
}

📘

Masked Fields

Sensitive fields like TIN are masked in API responses. Only the last 4 digits are visible (e.g., ****6789).

📘

Connection Status

New connections start in Requirements or Evaluating status. Once all required data is collected, the status automatically transitions to Ready. The missingRequiredData array contains field paths (e.g., owners[0].ssn, banking[0].routing) indicating exactly which data points are still needed. See Onboarding Data Requirements for a complete field path reference.

API Reference: createMerchant

Update Merchant

Updates merchant business information. Use this to add or modify business details after initial creation.

PATCH /v1/merchants/:merchantId

Request Body:

{
  "annualSaleVolume": 50000000,
  "averageTicket": 15000,
  "dateEstablished": "2020-01-15"
}

📘

Monetary Values

Monetary fields like annualSaleVolume, averageTicket, and highTicket are represented as whole numbers in cents (multiplied by 100). For example, $500,000.00 annual sales volume is 50000000, and $150.00 average ticket is 15000.

API Reference: updateMerchant

Add Owner

Adds a business owner to the merchant. Most processors require at least one owner with 25%+ ownership or a primary representative. Owner requirements vary by processor—some require full SSN while others only need the last 4 digits. See Processor Variations for details.

POST /v1/merchants/:merchantId/owners

Request Body:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "15559876543",
  "dob": "1985-03-15",
  "ssn": "123456789",
  "ownershipPercent": 100,
  "primaryRepresentative": true,
  "address": {
    "address1": "456 Oak Ave",
    "city": "Austin",
    "region": "TX",
    "postal": "78702",
    "country": "USA"
  }
}

📘

SSN Format

SSN must be provided as a 9-digit number without dashes or spaces (e.g., 123456789). Phone numbers use E.164 format without separators.

Response:

{
  "id": "midOwn_6pm1jgqtwc9qa98vb4wqwcxwng",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "15559876543",
  "dob": "*****-03-15",
  "ssn": "*****6789",
  "ownershipPercent": 100,
  "primaryRepresentative": true,
  "address": { ... }
}

📘

Masked Response

Sensitive fields like SSN and DOB are masked in API responses. SSN shows only the last 4 digits, and DOB shows only the month and day.

API Reference: addMerchantOwner

Update Owner

Updates an existing owner's information.

PATCH /v1/merchants/:merchantId/owners/:ownerId

API Reference: updateMerchantOwner

Add Bank Account

Adds a bank account for settlement deposits. Banking requirements vary by processor—some require account type while others do not. See Processor Variations for details.

POST /v1/merchants/:merchantId/bankaccounts

Request Body:

{
  "accountName": "Wells Fargo",
  "nameOnAccount": "Acme Corporation LLC",
  "accountType": "checking",
  "routing": "021000021",
  "account": "123456789",
  "primaryAccount": true,
  "country": "USA"
}

Response:

{
  "id": "midBank_5kaft3yde39cssvv3w389kens8",
  "accountName": "Wells Fargo",
  "nameOnAccount": "Acme Corporation LLC",
  "accountType": "checking",
  "routing": "****0021",
  "account": "****6789",
  "primaryAccount": true,
  "country": "USA"
}

📘

Masked Response

Bank account and routing numbers are masked in API responses for security. Only the last 4 digits are visible.

API Reference: addMerchantBank

Update Bank Account

Updates an existing bank account.

PATCH /v1/merchants/:merchantId/bankaccounts/:bankId

API Reference: patchBankDetails

Update Connection Details

Updates connection-specific data such as terms acceptance, custom requirement templates, or connection-specific requirements. For information on custom requirement templates and when to use them, see Custom Requirement Templates.

PATCH /v1/merchants/:merchantId/connections/:connectionId

Request Body (Terms Acceptance):

{
  "connectionspecificRequirements": {
    "tosDate": "2024-01-15T14:30:00Z",
    "tosVersion": "2024-01",
    "tosIp": "192.168.1.100"
  }
}

Request Body (Custom Template):

{
  "requirementsTemplate": "reqTemp_exd4sjvk483zrz7e4anyh12kr"
}

API Reference: patchConnectionDetails

Get Merchant Requirements

Returns the merchant record with detailed requirement information for each connection, including which fields are still missing. For a comprehensive guide on how Preczn evaluates requirements, including field path references and processor variations, see Onboarding Data Requirements.

GET /v1/merchants/:merchantId/requirement

Response:

{
  "id": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "name": "Acme Corp",
  "connections": [
    {
      "id": "midCon_6v59stftbs837axmpahj21m8jf",
      "processor": "Payrix",
      "status": "Ready",
      "missingRequiredData": []
    }
  ]
}

When missingRequiredData is empty and status is Ready, the merchant is eligible for onboarding submission.

API Reference: getMerchantRequirement

Initiate Onboarding

Submits the merchant to the processor for underwriting. The connection must be in Ready, RFI, or Error status.

POST /v1/merchants/:merchantId/connections/:connectionId/onboard

Success Response (200):

{
  "id": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "status": "Queued",
  "processor": "Payrix"
}

Error Response (400):

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

📘

Asynchronous Processing

Onboarding is asynchronous. The response returns Queued or Sent status, indicating the process has started. Subscribe to merchant.updated webhooks to receive status updates as the application moves through underwriting.

API Reference: onboardMerchantToConnection

Add Attachment

Uploads a file attachment to the merchant record. Attachments support onboarding and RFI responses but are not tracked as requirements—they won't appear in missingRequiredData or affect connection status transitions. See Onboarding Data Requirements for more on what is tracked.

POST /v1/merchants/:merchantId/attachments
Content-Type: multipart/form-data

Form Fields:

API Reference: addMerchantAttachment

Create Boarding Form

Generates a Preczn-hosted boarding form link for the merchant to complete their application. The form dynamically displays fields based on the connection's requirements. See Boarding Forms for setup and customization options.

POST /v1/forms

Request Body:

{
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "formTemplateId": "formTemp_1abc2def3ghi4jkl",
  "returnUrl": "https://yourapp.com/onboarding/complete"
}

Response:

{
  "id": "form_5mno6pqr7stu8vwx",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "formUrl": "https://forms.preczn.com/form_5mno6pqr7stu8vwx",
  "status": "pending"
}

The formUrl is the link to send to the merchant. When they complete the form, they're redirected to the returnUrl.

API Reference: createForm

Webhook Integration

Subscribe to merchant webhooks to receive real-time updates during onboarding:

Event: merchant.updated

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

Key status transitions to monitor:

• Requirements → Ready: All data collected, eligible for submission
• Queued → Sent: Data transmitted to processor
• Sent → Underwriting: Processor reviewing application
• Underwriting → Active: Approved and ready to process payments
• Underwriting → RFI: Processor requesting additional information
• Underwriting → Rejected: Application declined

See also: Webhooks

Error Handling

All endpoints return standard error responses:

Example Error Response:

{
  "statusCode": 400,
  "message": "The submitted requirementTemplate not found.",
  "error": "Bad Request"
}

Related Pages

• Merchant Onboarding - Onboarding concepts and workflow
• Onboarding Data Requirements - Understanding requirements
• Boarding Forms - Preczn-hosted data collection