Configuration

Every option is passed to OsiguPreAuth.mount({...}) when you initialise the widget. Options are grouped by concern below.

Required

Option	Type	Purpose
container	string | HTMLElement	CSS selector or DOM node the widget will render into.
getToken	() => Promise<string>	Called whenever the widget needs an access token. Return your cached token from a server-side proxy.
environment	'sandbox' | 'production'	Which Osigu environment to talk to. Affects both API base URL and OTP delivery.

Common

Option	Type	Purpose
sponsorSlug	string	Lock the widget to a specific sponsor. Omit to let the beneficiary picker filter across all affiliated sponsors.
productType	'MEDICATION' | 'LAB' | 'IMAGING' | 'PROCEDURE'	Lock the flow to a single product type. Omit for a picker.
locale	'en' | 'es' | 'pt-BR'	UI language. Defaults to browser locale.
theme	'light' | 'dark' | 'auto'	Colour scheme. auto follows the user's OS preference.

Prefill

Prefill saves the beneficiary the trouble of re-typing what your app already knows.

Option	Type	Purpose
prefill.beneficiaryId	string	Skip beneficiary search — go straight to product selection with this ID.
prefill.beneficiarySearchInput	object	Pre-fill the search form values (e.g. { document_type: 'CC', document_number: '...' }). User can still edit.
prefill.diagnosisCode	string	Preselect the diagnosis.
prefill.products	Array<{product_code, quantity, posology?}>	Preselect one or more products.

Behaviour hooks

Option	Type	Purpose
hooks.beforeSubmit	async (payload) => payload | false	Called with the request payload just before POST /authorization-requests. Return a modified payload to mutate; return false to cancel.
hooks.onStepChange	(step) => void	Fires whenever the widget moves to a new step. Useful for analytics.
hooks.decorateSearchResult	(beneficiary) => beneficiary	Post-process the beneficiary object before the user sees it.

Callback events

Option	Signature	Purpose
onReady	() => void	Widget is mounted and ready.
onComplete	(outcome) => void	User finished the flow. See Events for the shape.
onError	(err) => void	Something went wrong. See Events for err shape.
onClose	() => void	User closed the widget without completing.

Telemetry

Option	Type	Purpose
telemetry.trackingId	string	Optional identifier attached to internal request logs (e.g. your session ID). Osigu's support team can trace by this.
telemetry.disabled	boolean	Set true to opt out of Osigu's usage analytics. Default false.

Advanced

Option	Type	Purpose
apiBaseUrl	string	Override the API host. Only use if Osigu's ops team explicitly gave you a private URL.
debug	boolean	Log verbose events to the console. Off by default.

Full example

OsiguPreAuth.mount({
  container: '#osigu-preauth',
  getToken: async () => (await fetch('/api/osigu/token')).json().then(r => r.access_token),
  environment: 'sandbox',

  sponsorSlug: 'sponsor-sandbox',
  productType: 'MEDICATION',
  locale: 'es',
  theme: 'auto',

  prefill: {
    beneficiaryId: 'bnf_01HW8...',
    diagnosisCode: 'R51',
    products: [{ product_code: 'MED-042', quantity: 30, posology: '1c/8h' }],
  },

  hooks: {
    beforeSubmit: async (payload) => {
      // stamp our internal case number
      payload.additional_data = { ...payload.additional_data, case_id: myCaseId };
      return payload;
    },
    onStepChange: (step) => analytics.track('preauth_step', { step }),
  },

  telemetry: {
    trackingId: `session-${sessionId}`,
  },

  onReady: () => console.log('widget ready'),
  onComplete: (outcome) => {
    if (outcome.authorizations[0].status === 'APPROVED') {
      redirect(`/authorizations/${outcome.authorizations[0].authorization_code}`);
    }
  },
  onError: (err) => Sentry.captureException(err),
  onClose: () => history.back(),
});

Related

• Events — payload shapes for the callbacks.
• Customization — theming beyond theme: 'auto'.