Skip to content

IRIS (IrisPay) — Authentication & Access

Status: reconstructed from the OpenAPI spec (iris-*-openapi.json). Items marked [confirm on onboarding] are not in the public spec and must be filled from IRIS partner onboarding.

Environments

Env Base URL
Sandbox https://developer.sandbox.irispay.bg
Production https://developer.irispay.bg

Swagger UI: …/webjars/swagger-ui/index.html (prod) · …/swagger.html (sandbox).

Model

IRIS uses a layered hash/header scheme rather than a single API key. Requests carry one or more identity headers depending on the caller:

Header Represents
x-agent-hash The integrating partner ("IrisPay agent") — your top-level credential
x-user-hash An end-user (customer) enrolled under the agent
x-public-hash Public/unauthenticated-tier calls
x-admin-hash Administrative operations
consent-details Carries PSD2 consent context on account-information calls

An Authorization header is also referenced by the spec, and a JWKS endpoint (/api/6/.well-known/jwks.json) is published for JWT signature verification of tokens/webhooks.

Typical flow

  1. Become an IrisPay agent — obtain your agentHash / agent credentials from IRIS. [confirm on onboarding] how the agent hash and any Authorization secret are issued.
  2. Enroll a customer — POST /api/8/signup (requires agent identity; body SignupDTO: agentHash, companyName, uic, name, middleName, family, identityHash, email, webhookUrl).
  3. Get a user token — POST /api/8/usertoken with x-user-hash → returns a time-limited user token used for that customer's AIS/PIS calls.
  4. Register webhooks — POST /api/8/createhook (body AdditionalURLsHookDTO) for post-payment callbacks.
  5. Consent (account information) — POST /api/8/consent + consent-details, then call balances/transactions.

To obtain credentials

  • Contact IRIS Solutions: sales@irisbgsf.com / support@irisbgsf.com (see Offers & Brochures).
  • Request sandbox agent credentials for developer.sandbox.irispay.bg.
  • [confirm on onboarding]: exact Authorization value/format, token TTL, IP allow-listing, and how sandbox test users/IBANs are provisioned.