Skip to main content

Authorization events

The authorization.* family of events fires whenever a pre-authorization changes state, most often because a sponsor evaluated the request asynchronously and Osigu now knows the outcome.

If your integration only handles sponsors that evaluate synchronously, you may never see these events — you already got the outcome in the POST /authorization-requests/{id}/complete response. But building the receiver anyway is cheap insurance: sponsors switch modes without notice, and country regulations can move a sponsor from sync to async overnight.

Event types​

event_typeWhen it fires
authorization.createdThe sponsor approved a request that was PENDING_SPONSOR. authorization_code is now redeemable.
authorization.rejectedThe sponsor denied the request. rejection_reason explains why.
authorization.updatedA sponsor-originated modification (payment type change, product substitution, extended validity).
authorization.voidedThe authorization was cancelled — by the provider (voidAuthorization), by the sponsor, or by Osigu on expiry.

authorization.created​

Fires when the sponsor issues an authorization for a request that was previously PENDING_SPONSOR.

{
  "event_id": "evt_...",
  "event_type": "authorization.created",
  "created_at": "2026-06-25T14:22:11.789Z",
  "api_version": "2026-01-01",
  "environment": "sandbox",
  "data": {
    "authorization_id": "auth_01HXA...",
    "authorization_code": "AUTH-2026-001234",
    "authorization_request_id": "areq_01HX9KP...",
    "beneficiary_id": "bnf_01HW8GQ...",
    "sponsor_slug": "sponsor-sandbox",
    "product_type": "MEDICATION",
    "products": [
      { "product_code": "MED-042", "quantity": 30, "posology": "1c/8h" }
    ],
    "expires_at": "2026-07-25T00:00:00Z",
    "sponsor_reference": "SPX-2026-999",
    "additional_data": {}
  },
  "provider": { "provider_slug": "clinic-example" }
}

What to do: mark the pending request as approved in your database; make the code available for dispensation; notify the doctor / patient by whatever channel your product uses.

authorization.rejected​

The sponsor denied the request. No authorization was issued.

{
  "event_type": "authorization.rejected",
  "data": {
    "authorization_request_id": "areq_01HX9KP...",
    "beneficiary_id": "bnf_...",
    "sponsor_slug": "sponsor-sandbox",
    "rejection_reason": "Product not covered by plan GOLD-100",
    "sponsor_reference": "SPX-2026-999"
  }
}

What to do: surface the rejection_reason to the user. Do not rewrite the copy — sponsors care about the exact wording being surfaced.

authorization.updated​

Fires when an authorization is modified after issuance — typically the sponsor changes the payment type or extends the validity window.

{
  "event_type": "authorization.updated",
  "data": {
    "authorization_id": "auth_01HXA...",
    "authorization_code": "AUTH-2026-001234",
    "changes": {
      "payment_type": { "from": "IN_KIND", "to": "TRANSFER" },
      "expires_at": { "from": "2026-07-25T00:00:00Z", "to": "2026-09-25T00:00:00Z" }
    },
    "updated_at": "2026-06-30T10:00:00Z"
  }
}

What to do: patch your local copy. If a dispensation was in flight, re-fetch the authorization before completing.

authorization.voided​

Fires when the authorization is cancelled. Sources: provider (voidAuthorization), sponsor, Osigu (expiry).

{
  "event_type": "authorization.voided",
  "data": {
    "authorization_id": "auth_01HXA...",
    "authorization_code": "AUTH-2026-001234",
    "voided_at": "2026-06-30T11:00:00Z",
    "voided_by": "SPONSOR",  // or "PROVIDER" or "OSIGU"
    "reason": "Beneficiary coverage terminated"
  }
}

What to do: mark the authorization as void locally; if a dispensation was in progress against it, cancel that too.

Ordering caveats​

  • If a request goes PENDING_SPONSOR → APPROVED → VOIDED, you'll get authorization.created then authorization.voided for the same authorization_id.
  • Under rare race conditions, you may see authorization.voided before authorization.created. Treat this as a NOP — the sponsor cancelled before actually issuing.
  • Duplicate authorization.created events for the same authorization_id mean Osigu retried. Dedupe on event_id.