Quickstart

By the end of this page, a signed-in user of your app can fill in the formation wizard, pay in your checkout and land on their company’s dashboard, all in the test environment. Nothing is filed and nothing is charged.

Before you start

You need:

Your publishable test key (pk_test_...), from your sandbox account in the Partner Portal, under SDK → Install.
Your secret test key (dk_test_...), from Settings → API Keys in the same account. Keep it on your server.
An app with sign-in and a server that runs JavaScript. The steps use Next.js; the tabs show Express where it differs. For other languages, see Create sessions.

Put the secret key in your server’s environment:

.env

DOOLA_API_KEY=dk_test_your_api_key_here

1. Install

npm install @doola/js

2. Add a session route

This route creates a short-lived doola session for whoever is signed in to your app.

Next.js
Express

app/doola-session/route.ts

import { createSessionHandler } from '@doola/js/server';

export const POST = createSessionHandler({
  apiKey: process.env.DOOLA_API_KEY,
  getCustomer: async (request) => {
    const user = await getSignedInUser(request); // your own auth
    return user ? { email: user.email, externalCustomerId: user.id } : null;
  },
  onFailure: (failure) => console.error('doola session failed', failure),
});

import { createCustomerSession } from '@doola/js/server';

app.post('/doola-session', async (req, res, next) => {
  try {
    const user = await getSignedInUser(req); // your own auth
    if (!user) {
      res.status(401).end();
      return;
    }

    const { status, body, code, failure } = await createCustomerSession({
      apiKey: process.env.DOOLA_API_KEY,
      customer: { email: user.email, externalCustomerId: user.id },
    });

    if (failure) console.error('doola session failed', failure);

    res.set('Cache-Control', 'no-store');
    if (body) res.status(status).json(body);
    else if (code) res.status(status).json({ code });
    else res.status(status).end();
  } catch (error) {
    next(error);
  }
});

3. Mount the SDK

Render the SDK on a page your signed-in user can reach. When they submit the wizard, onFormed hands you the new company’s id.

app/formation/Formation.tsx

'use client';

import { loadDoola } from '@doola/js';
import { useEffect, useRef, useState } from 'react';

export function Formation() {
  const container = useRef<HTMLDivElement>(null);
  const [checkoutFor, setCheckoutFor] = useState<string | null>(null);

  useEffect(() => {
    if (checkoutFor) return;

    let element: HTMLElement | undefined;
    let unmounted = false;

    loadDoola({
      publishableKey: 'pk_test_your_publishable_key',
      fetchAccessToken: async () => {
        const r = await fetch('/doola-session', { method: 'POST' });
        if (!r.ok) {
          // Reject with the status and doola's error code: the loader maps them to error types.
          const { code } = await r.json().catch(() => ({}));
          throw Object.assign(new Error('doola session'), { status: r.status, code });
        }
        return r.json();
      },
      onAuthError: (error) => console.error('doola', error),
      onFormed: ({ companyId }) => setCheckoutFor(companyId),
    }).then((doola) => {
      if (unmounted) return;

      element = doola.create();
      container.current?.append(element);
    });

    return () => {
      unmounted = true;
      element?.remove();
    };
  }, [checkoutFor]);

  if (checkoutFor) return <Checkout companyId={checkoutFor} onDone={() => setCheckoutFor(null)} />;

  return <div ref={container} />;
}

This keeps the quickstart short by passing setCheckoutFor straight to loadDoola. That works here because the component never unmounts. In a real app, keep one instance outside your components, as shown in Embed the SDK.

4. Take payment and confirm it

Your checkout charges the founder, then your server tells doola. Until then, doola files nothing. For this test, the checkout is a single button.

app/formation/Checkout.tsx

'use client';

export function Checkout({ companyId, onDone }: { companyId: string; onDone: () => void }) {
  async function pay() {
    const r = await fetch(`/api/checkout/${encodeURIComponent(companyId)}/pay`, { method: 'POST' });
    if (r.ok) onDone(); // mounts the SDK again, which now shows the founder's company
  }

  return <button onClick={pay}>Pay for your company</button>;
}

On your server, check that the company belongs to the signed-in user and still waits on payment, charge, then confirm:

app/api/checkout/[companyId]/pay/route.ts

const DOOLA_API = 'https://api.test.doola.com';
const headers = { authorization: process.env.DOOLA_API_KEY!, 'content-type': 'application/json' };

async function doola<T>(path: string, init?: RequestInit): Promise<T> {
  const r = await fetch(`${DOOLA_API}${path}`, { ...init, headers });
  if (!r.ok) throw new Error(`doola ${path} answered ${r.status}`);

  const text = await r.text(); // payment-confirmed answers with an empty body
  return text ? JSON.parse(text).payload : undefined;
}

export async function POST(request: Request, { params }: { params: Promise<{ companyId: string }> }) {
  const user = await getSignedInUser(request); // your own auth
  if (!user) return new Response(null, { status: 401 });

  const { companyId } = await params;
  const company = await doola<{ doolaCustomerId: string; formationSubmissionStatus: string }>(
    `/v1/partner/companies/${encodeURIComponent(companyId)}`,
  );
  const owner = await doola<{ email?: string }>(
    `/v1/partner/customers/${encodeURIComponent(company.doolaCustomerId)}`,
  );
  if (owner.email?.toLowerCase() !== user.email.toLowerCase()) return new Response(null, { status: 404 });

  const paid = ['PENDING', 'SUBMITTED', 'COMPLETED'].includes(company.formationSubmissionStatus);
  if (!paid && company.formationSubmissionStatus !== 'AWAITING_PAYMENT') {
    return new Response(null, { status: 409 }); // CANCELLED, FAILED or unknown: never charge
  }

  if (!paid) {
    // Charge the founder here with your payment provider: one idempotency key per attempt.
    await doola(`/v1/partner/companies/${encodeURIComponent(companyId)}/payment-confirmed`, {
      method: 'POST',
      body: JSON.stringify({ partnerReference: `test-${companyId}` }),
    });
  }

  return new Response(null, { status: 204 });
}

Take payment covers pricing, retries, refunds and everything else a real checkout needs.

5. Try it

Sign in to your app and open the page with the SDK. The wizard appears, in your branding if you set it in the portal.
Fill it in and press Submit and pay. Your checkout replaces the SDK.
Press Pay for your company. The SDK mounts again and shows the founder’s company. Without an SSN, it first asks them to sign the IRS Form SS-4.
Read the company with your secret key: formationSubmissionStatus is now past AWAITING_PAYMENT.

That is a complete integration. Each customer forms one company, so sign in as a new user, or send a new email, to run it again.

Next steps

Take payment

Price on your server, charge once per company, and handle every edge case.

Branding

Your logo, colors and font, set in the Partner Portal.

After payment

Webhooks, documents and signatures once filing starts.

Go-live checklist

Everything to check before you switch to live keys.

Get started

Integrate

Customize

Test and launch

Reference

Help

Before you start

1. Install

2. Add a session route

3. Mount the SDK

4. Take payment and confirm it

5. Try it

Next steps

Take payment

Branding

After payment

Go-live checklist

​Before you start

​1. Install

​2. Add a session route

​3. Mount the SDK

​4. Take payment and confirm it

​5. Try it

​Next steps

Take payment

Branding

After payment

Go-live checklist

Before you start

1. Install

2. Add a session route

3. Mount the SDK

4. Take payment and confirm it

5. Try it

Next steps