Skip to main content

Onboarding Status

This document explains how partners can track the onboarding status of their client merchants through the Rootline Dashboard and webhooks.

For a visual overview of the onboarding flow, see the Merchant Onboarding Flow presentation.

Viewing Company Status in the Dashboard​

Partners can monitor the onboarding progress of their client merchants in the Companies section of the Rootline Dashboard.

Verification Status​

Each company has a verification_status that indicates where they are in the onboarding process:

StatusDefinition
createdCompany has been created, merchant has not provided information or accepted Terms of Service.
openMerchant has submitted the onboarding form and accepted Terms of Service. Verification is in progress.
verifiedMerchant has passed all verification checks and is approved to transact.
not_acceptedFinal rejection. Merchant will not be onboarded (e.g., prohibited business, failed KYC).
suspendedNon-response clients (never verified). Or verified customers that fail a Periodic Review or Enhanced Due Diligence Review.

Next Action​

When additional steps are required from the merchant, the next_action field will be populated with:

  • Action Type: What needs to be done (e.g., provide_information, await_assessment)
  • Onboarding URL: A link where the merchant can submit the required information
  • Comment: Details about what information is needed

Onboarding Flows​

Two onboarding flows coexist:

Onboarding URL​

Two URL shapes exist, and which one applies depends on the flow:

  • Company-specific link — https://onboarding.rootline.com/example.com/{company_id}
  • Global onboarding link — https://onboarding.rootline.com/example.com/merchants

Once a company exists, all further interactions with the merchant go through the company-specific link — any additional information request uses this URL.

A checklist of the information merchants need to prepare before starting the onboarding form is available at Merchant Onboarding Requirements. Partners can share this with their merchants ahead of time.

The partner pre-creates a company via POST /v1/companies or through the Rootline Dashboard. The response includes a company-specific onboarding URL.

  1. Partner calls POST /v1/companies or creates a company through the Dashboard — company starts as created with next_action.type = provide_information
  2. Partner sends the onboarding URL to the merchant
  3. Merchant opens the link and completes the onboarding form + accepts ToS
  4. Company transitions to open with next_action.type = await_assessment

The partner shares their global onboarding link (e.g., https://onboarding.rootline.com/example.com/merchants).

  1. Merchant fills in the onboarding form and accepts ToS
  2. Company is created directly with verification_status = open and next_action.type = await_assessment

Additional Information Requests​

After a merchant submits the onboarding form, Rootline may need additional information to complete the verification. When this happens, the company's next_action is updated to provide_information with a link to a partial form containing only the specific fields that need to be completed.

How it works​

  1. Rootline determines that additional information is needed (e.g., an expired passport, missing tax number, or unclear ownership structure)
  2. The company's next_action is updated:
    • type changes to provide_information
    • onboarding_url points to the same company-specific URL
    • comment describes what information is needed
  3. A company.next_action.updated webhook is sent to notify the partner
  4. The partner forwards the onboarding URL to the merchant. The merchant opens the onboarding URL and a targeted form is displayed with only the fields that need to be completed
  5. After submission, next_action changes to await_assessment while Rootline reviews the new information

When it can happen​

Additional information requests can occur at different stages:

Company statusScenarioExample
openDuring initial verificationMissing documents, unclear ownership structure
verifiedPeriodic review or event-driven reviewExpired passport, annual KYC refresh, new compliance requirements

Partner integration​

When you receive a company.next_action.updated webhook with type = provide_information:

  1. Read the comment field to understand what information is needed
  2. Forward the onboarding_url to the merchant, or direct them to complete the form
  3. Monitor for a subsequent company.next_action.updated webhook indicating the status has changed to await_assessment (submission received) or the verification has completed

State Mapping and Transitions​

Scenarioverification_statusnext_actionNotes
Company created via API or Dashboard (Flow A)createdprovide_informationMerchant needs to open onboarding link and submit form
Merchant submitted company information and accepted ToS (Flow A)openawait_assessmentTransition from created to open
Merchant submitted company information and accepted ToS (Flow B)openawait_assessmentCompany created directly as open
Additional information neededopenprovide_informationRootline requests specific fields via the same onboarding URL
Stale or duplicate onboardingsuspendednullCompany onboarding will not be picked up further
Verification complete, approvedverifiednullMerchant can transact
Verified, periodic review triggeredverifiedreview_informationE.g., annual KYC refresh, event-driven review
Verified, additional info neededverifiedprovide_informationNew terms, expiring passport
Rejected (prohibited industry, failed KYC)not_acceptednullFinal, no further action

Status Flow​

                    ┌─────────────────┐
                    │     created     │ <-- Flow A (POST /v1/companies)
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │      open       │ <-- Flow B (global onboarding link)
                    └────────┬────────┘
                             │
           ┌─────────────────┼─────────────────┐
           │                 ▲                 │
           │                 │                 │
           ▼                 ▼                 ▼
    ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
    │  verified   │──►│  suspended  │   │not_accepted │
    └─────────────┘   └─────────────┘   └─────────────┘

Onboarding by environment​

Production is the live onboarding flow — do not use it for testing. All companies submitted in production go through the full verification process by Rootline's operations team, and there are no test parameters or test modes. Use the staging environment for any trial runs.

What to expect after a merchant submits the onboarding form in production:

  1. Rootline reviews the submitted information
  2. If additional information is needed, a company.next_action.updated webhook is sent with type = provide_information
  3. Once verification is complete, the company transitions to verified and processing accounts are created

Webhooks​

Partners can subscribe to webhooks to receive real-time notifications when company status or next action changes. For setup instructions (endpoint configuration, HMAC signature verification, delivery guarantees), see the Configure webhooks guide.

The two onboarding-related event payloads are shown below.

company.verification_status.updated​

The verification status of a company was updated.

{
    "object": "event",
    "webhook_endpoint_id": "webh_4WxqjT0YfsxXDeKPbrwRie",
    "event_type": "company.verification_status.updated",
    "event_time": "2024-12-24T14:18:11.435566Z",
    "livemode": false,
    "api_version": "2024-04-23",
    "company": {
        "id": "co_5IGIrh15JJZ5oKSYubFpEr",
        "object": "company",
        "name": "JoesCanteen",
        "company_name": "Joe's Canteen B.V.",
        "created_at": "2024-12-24T14:18:11.422Z",
        "reference": "myRefForUser1",
        "verification_status": "verified"
    }
}

company.next_action.updated​

The next action required for a company was updated.

{
    "object": "event",
    "webhook_endpoint_id": "webh_4WxqjT0YfsxXDeKPbrwRie",
    "event_type": "company.next_action.updated",
    "event_time": "2024-12-24T14:18:11.435566Z",
    "livemode": false,
    "api_version": "2024-04-23",
    "company": {
        "id": "co_5IGIrh15JJZ5oKSYubFpEr",
        "object": "company",
        "name": "JoesCanteen",
        "company_name": "Joe's Canteen B.V.",
        "created_at": "2024-12-24T14:18:11.422Z",
        "reference": "myRefForUser1",
        "verification_status": "open",
        "next_action": {
            "type": "provide_information",
            "onboarding_url": "https://onboarding.rootline.com/..."
        }
    }
}