RegulaView Operator Reporting API

Quickstart

Minimum viable production integration

Operators report continuously over HTTPS. RegulaView accepts signed source events, deduplicates retries, validates the stream, reconciles independent totals, and seals each reporting day into a manifest.

1. 1
   Get a token

   Exchange issued client credentials for a short-lived access token and cache it until close to expiry.

2. 2
   Retrieve the daily signing key

   Use the key for the UTC day of the transaction timestamp.

3. 3
   Sign and report transactions

   Send every wager, payout, void, refund, adjustment, deposit, and withdrawal.

4. 4
   Send operational evidence

   Heartbeat devices, submit responsible-gaming events, and send cashier or payment-provider totals.

5. 5
   Declare daily tax details

   Submit aggregate tax details after the business day closes.

6. 6
   Correct through append-only requests

   Use correction requests for after-the-fact changes instead of altering accepted events.

7. 7
   Countersign the manifest

   After the day is sealed, sign the Merkle root with the same daily key.

Environments and versioning

Use the same v1 paths everywhere

URL versioning is canonical. All endpoints in this guide use /v1. The optional X-RegulaView-Api-Version: 1.0 header is accepted for client tooling metadata, but the URL segment is the source of truth.

Authentication

Request an access token

Each operator receives a client ID, client secret, and scopes during onboarding. The bearer token identifies the licensed entity and scopes every subsequent request.

POST /v1/auth/token HTTP/1.1
Host: api.regulaview.io
Content-Type: application/json
X-Correlation-Id: op-token-20260430-0001

{
  "clientId": "<your-client-id>",
  "clientSecret": "<your-client-secret>",
  "grantType": "client_credentials"
}

{
  "accessToken": "eyJhbGciOi...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "ingest:write read:own"
}

Headers and data formats

Standard request shape

Transaction signing

Sign the exact transaction being submitted

Retrieve one daily key per UTC reporting day, then sign every transaction with the key for that transaction's occurredAtUtc day. Single submissions carry the signature in X-RegulaView-Signature; batch submissions carry signature on each item.

GET /v1/integrity/manifests/2026-04-30/signing-key HTTP/1.1
Authorization: Bearer <accessToken>

{
  "day": "2026-04-30",
  "keyId": "manifest-20260430",
  "secretBase64": "<daily-operator-hmac-secret>",
  "algorithm": "HMAC-SHA256",
  "validFromUtc": "2026-04-30T00:00:00Z",
  "validToUtc": "2026-05-01T00:00:00Z"
}

{keyId}|{deviceIdentity}|{externalId}|{type:int}|{product:int}|{amount:F4}|{currency}|{occurredAtUnixMs}|{chainReference}|{correlationId}

const crypto = require("crypto");

function signTransaction(key, tx) {
  const type = { Wager: 0, Payout: 1, Adjustment: 2, Void: 3, Refund: 4, Deposit: 5, Withdrawal: 6 }[tx.type];
  const product = { OnlineCasino: 0, PhysicalCasino: 1, RetailGambling: 2, SportsBetting: 3, VirtualGames: 4, Lotto: 5, InstantWin: 6, Keno: 7, Bingo: 8, GamingMachine: 9, Jackpot: 10, ParimutuelRacing: 11, MobileGambling: 12, Poker: 13, VirtualSports: 14, ScheduledGames: 15, Other: 99 }[tx.product ?? "Other"];
  const canonical = [
    key.keyId,
    tx.deviceExternalId ?? "",
    tx.externalId,
    type,
    product,
    Number(tx.amount).toFixed(4),
    tx.currency,
    new Date(tx.occurredAtUtc).getTime(),
    tx.chainReference ?? "",
    tx.correlationId ?? ""
  ].join("|");

  return crypto.createHmac("sha256", Buffer.from(key.secretBase64, "base64"))
    .update(canonical, "utf8")
    .digest("hex");
}

Ingestion

Submit a signed transaction

Send each wager, payout, void, refund, adjustment, deposit, and withdrawal as a distinct event. Use your own stable externalId for the transaction and deviceExternalId for the source device.

POST /v1/ingest/transactions HTTP/1.1
Host: api.regulaview.io
Authorization: Bearer <accessToken>
Content-Type: application/json
Idempotency-Key: 8c8a6a5b-6c37-4f1a-89c6-6264de4663c0
X-RegulaView-Signature: <lowercase-hex-hmac>
X-Correlation-Id: tx-OP-20260430-000001

{
    "externalId": "OP-20260430-000001",
    "deviceExternalId": "shop-014-terminal-02",
    "type": "Wager",
    "amount": 5.00,
    "currency": "EUR",
    "occurredAtUtc": "2026-04-30T10:30:00Z",
    "product": "Lotto",
    "chainReference": "TICKET-20260430-A1B2",
    "correlationId": "ticket-processor-7"
}

{
  "receipt": {
    "transactionId": "f4c1a3d2-3b61-4a8b-a9cb-65258c03c503",
    "externalId": "OP-20260430-000001",
    "status": "accepted",
    "payloadHash": "6e8c...",
    "idempotencyKey": "8c8a6a5b-6c37-4f1a-89c6-6264de4663c0",
    "location": "/v1/transactions/f4c1a3d2-3b61-4a8b-a9cb-65258c03c503",
    "message": null
  }
}

Batch and retry

Use batches for catch-up and store-and-forward

The batch endpoint accepts up to 5000 transactions. Preserve the original occurredAtUtc, sign each item individually, and put per-item idempotencyKey values in the request body.

POST /v1/ingest/transactions/batch HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
    "transactions": [
        {
            "externalId": "OP-20260430-000002",
            "deviceExternalId": "shop-014-terminal-02",
            "type": "Wager",
            "amount": 10.00,
            "currency": "EUR",
            "occurredAtUtc": "2026-04-30T12:35:01Z",
            "product": "SportsBetting",
            "idempotencyKey": "OP-20260430-000002",
            "signature": "<lowercase-hex-hmac>"
        }
    ]
}

Daily tax declarations

Submit aggregate tax details after close

Transaction reporting is real time. Tax declarations are the operator's daily aggregate statement, submitted after the reporting day closes. A declaration for the same day replaces the previous declaration inside the accepted window, making late changes explicit and auditable.

POST /v1/tax/declarations HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "day": "2026-04-30",
  "grossWagers": 125000.00,
  "payouts": 91000.00,
  "declaredTax": 5100.00
}

{
  "day": "2026-04-30",
  "grossWagers": 125000.00,
  "payouts": 91000.00,
  "netRevenue": 34000.00,
  "calculatedTax": 5100.00,
  "declaredTax": 5100.00,
  "variance": 0.00
}

Cashier reconciliation

Send independent payment or cashier totals

Reconciliation totals give the regulator an independent ground-truth feed to compare against transaction-derived cash-in and cash-out activity.

POST /v1/recon/cashier-totals HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "day": "2026-04-30",
  "cashIn": 48000.00,
  "cashOut": 36500.00,
  "outletReference": "SHOP-014",
  "source": "cashier-close-v2"
}

Devices and responsible gaming

Report operational state and player-protection events

Heartbeats show whether the reporting estate is alive. Responsible-gaming events surface policy triggers and high-risk patterns for regulatory review.

POST /v1/devices/external/terminal-alpha-07/heartbeat HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "configurationVersion": "2026.04.30.1",
  "configurationHash": "b6e4f8b7266f4d2e998c7f2a0f1be75c",
  "gameEnabled": true,
  "health": "Healthy"
}

POST /v1/rg/events HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "type": "LimitBreach",
  "severity": "High",
  "deviceExternalId": "terminal-alpha-07",
  "pseudonymousPlayerRef": "player-hash-91b2",
  "summary": "Daily loss threshold breached",
  "evidence": "loss=500;threshold=500;currency=EUR"
}

Corrections

Fix accepted events through append-only requests

Corrections create a reviewed delta record. They do not mutate the original accepted transaction or the manifest that sealed it.

POST /v1/corrections HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "originalExternalId": "OP-20260430-000001",
  "reason": "Operator settlement system corrected payout amount after manual review.",
  "payloadDiff": [
    {
      "path": "/amount",
      "from": 5.00,
      "to": 4.50,
      "reason": "Manual settlement review corrected the amount."
    }
  ]
}

Daily attestation

Countersign the sealed manifest

After the platform seals the day's hash-chain entries into a Merkle manifest, retrieve the manifest, compute the attestation HMAC, and submit it within the jurisdiction's attestation window.

{merkleRoot}|{day:yyyy-MM-dd}|{operatorId:N}

POST /v1/integrity/manifests/2026-04-30/attest
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "merkleRoot": "a803...b1",
  "signature": "5e7d...a4"
}

Endpoint reference

Core v1 endpoints

Errors

Problem responses are stable and supportable

Errors use a standard problem envelope with errorCode, message, status, correlationId, requestId, and timestampUtc. Quote the correlation and request IDs in support cases.

{
  "type": "idempotency_conflict",
  "title": "Idempotency key conflict",
  "status": 409,
  "detail": "The same Idempotency-Key was already used with a different transaction payload.",
  "correlationId": "op-2026-04-30-000001",
  "requestId": "0HMT...",
  "timestampUtc": "2026-04-30T12:34:56Z",
  "errors": null
}

Rate limits

Sandbox testing capacity policies

The defaults below describe the sandbox and certification environment used during integration testing. Production limits are agreed during operator onboarding and may differ based on certified throughput and regulatory requirements.

Certification checklist

What operators should prove before go-live

• Token caching and refresh before expiry.
• Daily signing-key retrieval for each UTC transaction day.
• Valid signatures for all seven transaction types.
• Duplicate replay returns duplicate receipts and is treated as success.
• Idempotency and external-ID conflicts stop processing and alert the operator team.
• Batch replay works after an offline store-and-forward period.
• Device heartbeats arrive on the agreed cadence.
• Tax declarations and cashier totals are submitted after close.
• Manifest countersignature succeeds for a sealed reporting day.
• Support tickets include correlation ID and request ID.