Payroll Integration

When using the marketplace flow, your application needs to handle payroll authorization so Benbase can access employer payroll data for census sync and benefits quoting.

Iframe events

The marketplace flow emits an event when the employer needs to authorize payroll data access.

benbase-embed.authorize-start Triggered when the user clicks "Import from Payroll" inside the marketplace iframe. The event payload contains the organizationId of the employer.

Event listener example

window.addEventListener('message', (event) => {
    const { event: eventName, data } = event.data;

    switch (eventName) {
        case 'benbase-embed.authorize-start':
            const { organizationId } = data;
            // Initiate Check payroll authorization (see below)
            initiatePayrollAuthorization(organizationId);
            break;

        case 'benbase-embed.height-updated':
            const { height } = data;
            iframe.style.height = `${height}px`;
            break;
    }
});

To authorize Benbase to access an employer's payroll data, you need to initiate the Check OAuth integration flow. As the Check Partner, you call Check's authorization component endpoint and redirect the user to the consent screen. Benbase receives the OAuth callback directly from Check — you do not need to handle or forward any authorization codes.

Prerequisites

Your Check Partner API key
Benbase integration ID: int_DjupWSJkIYfQ2xfIB3sL
Benbase integration permission ID: ipe_keLxIxEPasWS9Za6UKCu

Authorization flow

Step 1: Listen for the benbase-embed.authorize-start event

When the event is received, extract the organizationId from the payload. This is the Check company ID for the employer.

Step 2: Call Check's authorization component endpoint

From your server, call the Check API to get the authorization component URL.

POST https://sandbox.checkhq.com/companies/{company_id}/components/integrations/authorize

Request headers:

Authorization - Bearer {YOUR_CHECK_API_KEY}

Request body:

integration_partner - int_DjupWSJkIYfQ2xfIB3sL (Benbase integration ID)
integration_permission - ipe_keLxIxEPasWS9Za6UKCu (Benbase integration permission ID)
email - Contact email for the employer
redirect_url - URL in your application where the user should return after authorization

curl -X POST https://sandbox.checkhq.com/companies/{company_id}/components/integrations/authorize \
  -H "Authorization: Bearer {{YOUR_CHECK_API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_partner": "int_DjupWSJkIYfQ2xfIB3sL",
    "integration_permission": "ipe_keLxIxEPasWS9Za6UKCu",
    "email": "employer@example.com",
    "redirect_url": "https://your-app.com/benefits"
  }'

Response:

{
  "url": "https://component.checkhq.com/..."
}

Step 3: Redirect the user

Redirect the user to the returned url. This renders Check's authorization consent screen where the employer grants Benbase access to their payroll data.

Step 4: User authorizes

The employer reviews and approves the authorization on Check's consent screen.

Step 5: Authorization completes

Two things happen in parallel:

Check redirects the user back to your redirect_url — the user returns to your application
Check separately sends the OAuth authorization to Benbase's registered callback. Benbase exchanges the code for tokens, stores the authorization, and triggers census sync and re-quoting with real payroll data automatically.

You do not need to handle or forward any OAuth codes. Benbase receives the authorization callback directly from Check.

Complete example

// 1. Listen for the authorize-start event from the Benbase iframe
window.addEventListener('message', (event) => {
    const { event: eventName, data } = event.data;

    if (eventName === 'benbase-embed.authorize-start') {
        initiatePayrollAuthorization(data.organizationId);
    }
});

// 2. Call your backend to get the Check authorization component URL
async function initiatePayrollAuthorization(companyId) {
    const response = await fetch('/api/check/authorize', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ companyId }),
    });

    const { url } = await response.json();

    // 3. Redirect the user to Check's authorization consent screen
    window.location.href = url;
}

Your backend endpoint (/api/check/authorize) should call the Check API:

// Server-side: call Check's authorization component endpoint
app.post('/api/check/authorize', async (req, res) => {
    const { companyId } = req.body;

    const response = await fetch(
        `https://sandbox.checkhq.com/companies/${companyId}/components/integrations/authorize`,
        {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${process.env.CHECK_API_KEY}`,
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                integration_partner: 'int_DjupWSJkIYfQ2xfIB3sL',
                integration_permission: 'ipe_keLxIxEPasWS9Za6UKCu',
                email: 'employer@example.com',
                redirect_url: 'https://your-app.com/benefits',
            }),
        }
    );

    const { url } = await response.json();
    res.json({ url });
});

For production, replace https://sandbox.checkhq.com with https://api.checkhq.com.