Onboarding

Onboarding covers getting a merchant set up on the platform: register the merchant, submit their business details to the processor (XplorPay/Clearent) for underwriting, and track approval until they have a live payment account. PayBridge manages the processor integration on your behalf — account creation, routing, and webhook delivery.

All requests use the base URL, X-API-Key, and X-Requested-With header from the Overview. Amounts are in cents.

Step 1: Register a merchant

Create a merchant record for the business you want to onboard.

POST /merchants

{
  "name": "Smith Custom Sheds",
  "business_name": "Smith Custom Sheds LLC",
  "business_type": "llc",
  "email": "john@smithsheds.com",
  "phone": "512-555-1234"
}

Response (201):

{
  "id": "a1b2c3d4-...",
  "name": "Smith Custom Sheds",
  "business_name": "Smith Custom Sheds LLC",
  "status": "active",
  "processors": [],
  "created_at": "2026-03-26T12:00:00Z"
}

Save the id — you'll use it for all subsequent calls.

Step 2: Submit onboarding

Collect all merchant details in your own UI and submit them to the processor for underwriting in a single call. PayBridge forwards everything to the processor's onboarding API.

POST /merchants/{merchant_id}/onboard

{
  "processor_type": "clearent",
  "business": {
    "legal_name": "Smith Custom Sheds LLC",
    "dba_name": "Smith Custom Sheds",
    "business_type": "llc",
    "ein": "27-1234567",
    "mcc_code": "5211",
    "website": "https://smithsheds.com",
    "annual_volume": 50000000,
    "average_ticket": 75000,
    "high_ticket": 250000,
    "card_present_percentage": 0
  },
  "principal": {
    "first_name": "John",
    "last_name": "Smith",
    "title": "Owner",
    "email": "john@smithsheds.com",
    "phone": "512-555-1234",
    "dob": "1985-06-15",
    "ssn": "123-45-6789",
    "country_of_citizenship": "US",
    "ownership_percentage": 100
  },
  "banking": {
    "routing_number": "021000021",
    "account_number": "123456789",
    "account_type": "checking",
    "bank_name": "Chase"
  },
  "physical_address": {
    "line1": "123 Workshop Lane",
    "city": "Austin",
    "state_code": "TX",
    "zip": "78701",
    "country_code": "US"
  }
}

Response (202 Accepted):

{
  "processor_id": "...",
  "type": "clearent",
  "onboarding_status": "submitted",
  "processor_merchant_id": "CLR_12345",
  "connected": false,
  "submitted_at": "2026-03-26T12:05:00Z"
}

connected becomes true once the processor account is approved and live credentials are stored.

Field names must match exactly — unknown or misspelled fields are rejected with HTTP 422. Beneficial owners who hold 25% or more of the business must be disclosed: the principal is the first owner, and any others go in an additional_owners array with their own ownership_percentage.

Sensitive fields

Fields like ein, ssn, dob, routing_number, and account_number contain PII and financial data. In sandbox you can submit them as raw values in the request body, exactly as shown above, and complete the full onboarding flow. Staging and production require these fields to be VGS-tokenized — raw values are rejected there; your integration contact provides the VGS Collect setup. Always send them over HTTPS, and never log or persist raw values.

Step 3: Track approval

Approval typically takes 1–3 business days while the processor's underwriting team reviews the application. You have two ways to track it.

Option A: Poll

GET /merchants/{merchant_id}/onboard/status

{
  "merchant_id": "a1b2c3d4-...",
  "processors": [
    {
      "processor_id": "...",
      "type": "clearent",
      "onboarding_status": "approved",
      "processor_merchant_id": "CLR_12345",
      "submitted_at": "2026-03-26T12:05:00Z",
      "approved_at": "2026-03-27T14:30:00Z",
      "rejection_reason": null
    }
  ]
}

Status progression: submitted → pending_review → approved or rejected.

Option B: Webhook

Register a webhook URL when your app is provisioned. PayBridge sends a signed POST to your URL when the status changes:

{
  "event_type": "merchant.approved",
  "webhook_id": "unique-id-for-deduplication",
  "merchant_id": "a1b2c3d4-...",
  "processor_type": "clearent",
  "processor_merchant_id": "CLR_12345",
  "onboarding_status": "approved",
  "timestamp": "2026-03-27T14:30:00Z"
}

Verify the X-PayBridge-Signature header before trusting a webhook, and always implement status polling as a fallback for missed events. Once a merchant is approved, you can start accepting Payments.