Skip to main content

Troubleshooting

Most widget issues fall into three buckets: loading, auth, or sponsor behaviour. This page walks the symptoms of each and how to isolate the cause.

Widget never appears​

Symptom: the host <div> is empty, no error in the console.

Check, in order:

  1. Is the loader script loading? Open Network tab, look for widgets.osigu.com/v1/loader.js. If it's blocked, CSP or an ad-blocker is at fault.
  2. Did you await window.osiguReady? If you call OsiguPreAuth.mount before the loader finished, OsiguPreAuth is undefined and mount throws silently. Always await window.osiguReady; first.
  3. Is the container selector correct? document.querySelector('#osigu-preauth') should return a real node. If not, mount errors are logged with [Osigu] prefix — filter the console.
  4. Height collapse? If the container has height: 0 and no min-height, the widget renders but is invisible. Add a min-height or let the widget size itself.

TypeError: Cannot read property 'access_token' of undefined​

Your getToken callback isn't returning what the widget expects.

The contract: getToken must return a Promise resolving to a string — the raw access_token value, not the full OAuth response.

// ❌ Wrong
getToken: async () => (await fetch('/api/osigu/token')).json()

// ✅ Right
getToken: async () => {
  const { access_token } = await (await fetch('/api/osigu/token')).json();
  return access_token;
}

WIDGET-TOKEN error​

Fired via onError. Two subvariants:

  • Token expired mid-flow. Your getToken returned a token whose exp has passed. Fix: don't cache the token past its expiry; the widget calls getToken per API call, so returning a fresh token here works.
  • Token missing scope. The token doesn't carry the scopes the widget needs (arc:read, arc:write). Check the scope field in /oauth/token response.

WIDGET-NETWORK error​

The widget retried a call three times and gave up. Check the browser's network tab for the failing endpoint. Common culprits:

  • CSP blocking connect-src https://sandbox.osigu.com.
  • Corporate proxy stripping Authorization headers.
  • Your token proxy (/api/osigu/token) is down.

OTP flow never resolves​

The user says they never received the code. Diagnose:

  1. Environment mismatch. Sandbox OTP goes to a mock delivery service (test SMS to a fake phone number). Production OTP goes to the real number of record. If you're in sandbox and the beneficiary is waiting on a real phone, that's why.
  2. Sponsor doesn't support OTP for this product type. Rare, but possible — the widget should not have triggered OTP. If you see this, email support@osigu.com with your trackingId.
  3. Rate limit hit. More than 5 OTP sends per hour for the same beneficiary/sponsor → 429. Wait an hour.

onComplete fires with authorizations[i].status === 'REJECTED'. The rejection_reason is set by the sponsor. Show it to the user — Osigu never re-writes sponsor rejection copy.

If you think the rejection is wrong, contact the sponsor's operations team, not Osigu. Osigu didn't make the decision; we just relayed it.

403 Forbidden in the network tab​

Two flavours:

  • 403 on /sponsors/{slug}/forms — Your provider isn't affiliated with this sponsor. Check listSponsors.
  • 403 on /authorization-requests — Your token doesn't carry arc:write, or the sponsor rejected the provider at the request-level (e.g. provider blocked). Contact Osigu support.

Widget iframe blocked​

Some CSPs block iframes by default. The OTP challenge and the biometric capture render in an Osigu-hosted iframe. Add:

frame-src https://widgets.osigu.com;

Analytics events missing​

You wired onStepChange but nothing fires? Check for silent mount failures — a mount error prevents onReady and everything downstream. Enable debug: true in the config; verbose logs will show why.

Getting help​

Include these in every support email:

  • Your trackingId (the value you set in telemetry.trackingId at mount time).
  • The timestamp of the failing session (browser time is fine).
  • The environment (sandbox / production).
  • A screenshot of the widget state when it failed.
  • The console error if any.

Email support@osigu.com.

  • Events — the onError.code values and what they mean.
  • Configuration — verify your options match the contract.