Server reference

@doola/js/server

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

Runs on Node 18 or later, or any runtime with the web-standard fetch, Request and Response. Both helpers send your key as the raw Authorization header, pick api.doola.com or api.test.doola.com from its prefix, and time out after 10 seconds.

createSessionHandler(options)

function createSessionHandler(options: {
  apiKey: string | undefined;
  getCustomer: (request: Request) => DoolaCustomer | null | Promise<DoolaCustomer | null>;
  onFailure?: (failure: CustomerSessionFailure) => void | Promise<void>;
}): (request: Request) => Promise<Response>;

Builds a complete session route.

apiKey: your dk_ secret key. A key that is set but invalid, including a pk_ key, throws when you create the handler. A missing key is refused on each request instead, so builds without the secret still pass.
getCustomer: return the signed-in customer, or null when nobody is signed in. null answers 401.
onFailure: called with the reason whenever doola does not return a session. Your own 401 for a signed-out user does not call it.

Every response carries Cache-Control: no-store. A success answers 200 with { accessToken, expiresIn }.

createCustomerSession(options)

function createCustomerSession(options: {
  apiKey: string | undefined;
  customer: DoolaCustomer;
}): Promise<{
  status: number;
  body: { accessToken: string; expiresIn: number } | null;
  code?: string;
  failure?: CustomerSessionFailure;
}>;

Creates one session and returns what your route should answer, for frameworks that do not use Request and Response: status, with body as JSON, or { code } as JSON when code is set (a 409). It rejects only when the key is missing or invalid.

DoolaCustomer

Field	Type	Notes
`email`	`string`	Required
`externalCustomerId`	`string`	Your user id, up to 255 characters. Matched before `email`
`firstName`, `lastName`	`string`	Used only when doola creates the customer
`countryOfResidence`	`string`	ISO 3166-1 alpha-3. Used only when doola creates the customer
`phoneNumber`	`string`	E.164. Used only when doola creates the customer

Only these fields are sent to doola, whatever else the object carries.

How doola’s answers map

doola answered	Your route answers	`failure.reason`
A session	200 with `{ accessToken, expiresIn }`
401	502	`doola_unauthorized`
409	409 with `{ code }`, doola’s error code, or no body when doola sent none	`doola_error`
Any other error	The same status, no body	`doola_error`
Nothing, or a timeout	502	`doola_unreachable`
A 2xx without a usable session	502	`invalid_response`

failure also carries doolaStatus and doolaCode, doola’s error.code, when there was one.

Partner API endpoints

An SDK integration uses five Partner API endpoints, all with your dk_ secret key:

Endpoint	Use it to
`POST /v1/partner/customer-sessions`	Create a session for the signed-in customer. See Create sessions
`GET /v1/partner/companies/{companyId}`	Check the company’s status before you charge
`GET /v1/partner/customers/{customerId}`	Check the company belongs to the signed-in customer
`GET /v1/partner/references/state-fees`	Price the state filing fee
`POST /v1/partner/companies/{companyId}/payment-confirmed`	Start the formation once you are paid. See Take payment

One more is optional:

Endpoint	Use it to
`GET /v1/partner/sdk/keys`	Read your publishable key from your server instead of copying it from the Partner Portal. It returns `{ publishableKey, createdAt }` and creates the key the first time you ask

Everything after payment, from webhooks to documents and required actions, uses the rest of the Partner API.

Get started

Integrate

Customize

Test and launch

Reference

Help

@doola/js/server

createSessionHandler(options)

createCustomerSession(options)

DoolaCustomer

How doola’s answers map

Partner API endpoints

​@doola/js/server

​createSessionHandler(options)

​createCustomerSession(options)

​DoolaCustomer

​How doola’s answers map

​Partner API endpoints

@doola/js/server

createSessionHandler(options)

createCustomerSession(options)

DoolaCustomer

How doola’s answers map

Partner API endpoints