Onboarding Status

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

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:

Status	Definition
open	Merchant has not (yet) completed verification. Onboarding may be in progress or not started yet.
verified	Merchant has passed all verification checks and is approved to transact.
not_accepted	Final rejection. Merchant will not be onboarded (e.g., prohibited business, failed KYC).
suspended	Non-response clients (never verified). Or verified customers that neglect to succeed next action or fail Enhanced Due Diligence Review / Periodic 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

State Mapping and Transitions

Scenario	verification_status	next_action	Notes
New signup	open	await_assessment	Operations team is reviewing
Onboarding in progress, data incomplete	open	provide_information	Merchant still needs to submit additional documents/info
No response after + weeks	suspended	null	Only partner can reactivate onboarding, with explicit request
Duplicate onboarding detected	suspended	null	Mark as stale, no action needed
Suspended after verification	suspended	null	Periodic Review / Enhanced Due Diligence Review lead to suspension of the account
Verification complete, approved	verified	null	Merchant can transact
Verified, periodic review triggered	verified	review_information	E.g., annual KYC refresh, event-driven review
Verified, additional info needed	verified	provide_information	New terms, expiring passport
Rejected (prohibited industry, failed KYC)	not_accepted	null	Final, no further action. Never verified.

Status Flow

                    ┌─────────────────┐
                    │      open       │
                    └────────┬────────┘
                             │
           ┌─────────────────┼─────────────────┐
           │                 ▲                 │
           │                 │                 │
           ▼                 ▼                 ▼
    ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
    │  verified   │──►│  suspended  │   │not_accepted │
    └─────────────┘   └─────────────┘   └─────────────┘

Webhooks

Partners can subscribe to webhooks to receive real-time notifications when company status or next action changes.

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": "TraderJoes",
        "company_name": "Trader Joe's",
        "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": "TraderJoes",
        "company_name": "Trader Joe's",
        "created_at": "2024-12-24T14:18:11.422Z",
        "reference": "myRefForUser1",
        "verification_status": "open",
        "next_action": {
            "type": "provide_information",
            "onboarding_url": "https://onboarding.rootline.com/..."
        }
    }
}

Configuring webhooks

To configure webhook events, please read our documentation about webhooks.

Staging Test Scenarios

Two test scenarios are available on the staging environment to test the full merchant onboarding flow — from company creation through to a fully configured processing account.

Use your personalized onboarding URL for staging and fill in the form, e.g. https://onboarding.staging.rootline.com/example.com/merchants

Scenario A: Direct Account Creation Flow

Use this scenario to test onboarding where the merchant is immediately verified and accounts are created. This is the simplest flow — no manual steps required, everything is created automatically.

How to trigger: Submit the onboarding form without a scenario parameter (the default behavior).

What happens:

1. Onboarding activation runs
2. Company is created with status open and next_action await_assessment
3. Company is immediately patched to verified
4. Account is created

Expected result: After activation completes, your merchant account is fully set up on staging with correct configurations.

Scenario B: Additional Information Request Flow

Use this scenario to test the full verification workflow, including the additional information form that merchants receive when extra details are required.

How to trigger: Add scenario=provide_information to the onboarding URL, e.g. https://onboarding.staging.rootline.com/example.com/merchants?scenario=provide_information

What happens:

1. Onboarding activation runs
2. Company is created with status open and next_action await_assessment
3. An additional information request form is generated — you will receive a webhook with the URL, company status remains open but next_action changes to provide_information
4. You fill in the form on the staging environment (the form asks for IBAN details)
5. After form submission, the system automatically:
   • Updates the company status to verified
   • Creates an account

Scenario Summary

	Scenario A	Scenario B
Trigger	Default (no scenario parameter)	scenario=provide_information in URL
Manual step required	No — fully automatic	Yes — fill in the additional info form
Simulates	Direct onboarding without additional info	Production flow with additional info request
End result	Fully configured merchant account	Fully configured merchant account