Unified Operator Integration Guide

1. Purpose and scope

This document is the operator-facing integration contract for the Prosper Aggregator. It describes only the unified APIs that an operator uses once across all supported game vendors. Included:

• Unified aggregator APIs under /api/v1/game-operators.
• Unified free-spins, jackpots, and promotions APIs under /api/v1/game-operators/promotions.
• Unified operator wallet callback API that the operator implements once for all game vendors.
• Credential handling needed to sign requests.
• Authentication, signing, DTOs, response envelopes, status codes, and integration checklist.

Any API not listed in this guide is outside the operator integration contract.

2. Base URL and unified routes

Use these integration bases:

Unified operator route inventory:

3. Authentication and signing

3.1 Operator to aggregator

Unified systematic routes use API-key HMAC headers:

HMAC payload rules for JSON requests:

• Build the JSON request body before signing.
• Use compact UTF-8 JSON: no spaces or newlines outside string values.
• Sign the same field names, values, and field order that are sent in the HTTP body.
• Do not sign a pretty-printed JSON body.
• Do not let the HTTP client mutate, reorder, or reserialize the body after signing.
• For a route with no body, sign an empty string.

The signature is the lowercase hexadecimal HMAC-SHA256 digest of that payload. Use the full provisioned secretKey, including the sk_ prefix, as the HMAC key when signing operator-to-aggregator calls. The game launch route requires the same HMAC validation as the other unified routes. Missing or invalid launch authentication returns an operator envelope with SC_INVALID_OPERATOR or SC_INVALID_SIGNATURE.

3.2 Aggregator to operator wallet

The aggregator calls the operator's configured callbackUrl with:

Wallet callback verification rules:

• Prosper sends wallet callbacks as compact UTF-8 JSON.
• Verify the signature against the raw HTTP request body received by the wallet endpoint.
• If the operator framework parses the request before application code can read it, enable raw-body capture for the wallet routes.
• Derive the wallet HMAC key by removing one leading sk_ prefix from the provisioned secretKey. If the secret has no sk_ prefix, use it unchanged.
• The expected signature is the lowercase hexadecimal HMAC-SHA256 digest.

4. Common response and error DTOs

4.1 Operator envelope

Most unified responses use:

4.2 Validation error

DTO validation failures return:

4.3 Unauthorized error

Authentication failures return:

5. Status code catalog

Wallet status normalization:

6. Operator-implemented unified wallet API

The operator implements this API once. The aggregator maps all supported game activity into these callbacks.

6.1 Wallet routes

6.2 Wallet request DTOs

OperatorBetResultRequest and OperatorRollbackRequest include all common transaction fields from OperatorBetRequest. OperatorAdjustmentRequest includes traceId, username, currency, amount, transactionId, adjustmentType, adjustmentTime, token, optional originalTransactionId, and optional details.

6.3 Wallet response DTOs

6.4 Wallet idempotency

• Idempotency key is transactionId.
• Enforce uniqueness by (operatorId, transactionId).
• Duplicate final bet, bet_result, rollback, and adjustment calls should return cached SC_OK snapshots without moving balance again.
• Unknown rollback original should return SC_TRANSACTION_NOT_FOUND.
• Already-rolled-back originals may return no-op SC_OK if the operator can prove the previous rollback completed.
• The aggregator wallet client does not retry automatically, but upstream systems can replay requests, so operator wallet behavior must be idempotent.

7. Unified aggregator API DTOs

7.1 List vendors — /game-operators/game/vendors

Request ListVendorsV1Dto:

Response data[]:

7.2 List games — /game-operators/game/list

Request ListGamesV1Dto:

Response data:

Game row indexes:

7.3 Game launch — /game-operators/game/url

Request RequestGameUrlV1Dto:

Response data:

7.4 Terminate session — /game-operators/game/terminate

Request TerminateGameV1Dto:

Response:

7.5 List transactions — /game-operators/transaction/list

Request ListTransactionsV1Dto:

Transaction row indexes:

7.6 Transaction detail — /game-operators/transaction/detail

Request GetTransactionDetailV1Dto:

Response data:

betDetail fields: betId, externalTransactionId, roundId, username, subOperator, currencyCode, gameCode, vendorCode, gameCategoryCode, betAmount, winAmount, winLoss, effectiveTurnover, jackpotAmount, refundAmount, status, isFreeSpin, vendorBetTime, and vendorSettleTime.

8. Unified free-spins, jackpots, and promotions API

This section defines the only operator-facing contract for free spins, free chips, jackpots, tournaments, prize drops, bonus cards, and promotion reporting. Operators call the same Prosper routes regardless of the upstream game vendor. Prosper owns all vendor routing and payload translation behind this API. All routes in this section use the authentication headers and HMAC signing rules from Section 3.1, and all responses use the operator envelope from Section 4.1.

8.1 Design model

Unified promotion and jackpot behavior is represented by these public concepts:

Promotion types:

Jackpots are not a promotionType unless Prosper later introduces an explicit jackpot campaign product. Operators use the jackpot routes for jackpot pools, jackpot winners, jackpot winnings, and contribution reports.

Campaign statuses:

8.2 Route inventory

All routes are relative to https://<aggregator-host>/api/v1.

8.3 Shared promotion DTOs

Common request fields:

Timestamps are Unix epoch seconds unless the field explicitly says otherwise.

FreeSpinsReward:

FreeChipsReward:

TournamentReward, PrizeDropReward, and BonusCardReward:

PromotionCampaign:

PromotionPlayer:

PromotionPlayerState:

8.4 Jackpot DTOs

JackpotPool:

JackpotWinner:

JackpotWinning:

JackpotContribution:

8.5 Campaign lifecycle endpoints

Create campaign — /game-operators/promotions/campaigns/create

Request CreatePromotionCampaignRequest:

Response data:

Idempotency:

• Repeating the same requestId with the same body returns the same campaign result.
• Reusing the same requestId with different campaign content returns SC_DUPLICATE_REQUEST.
• Reusing an existing campaignId with a different requestId returns SC_PROMOTION_ALREADY_EXISTS.

List campaigns — /game-operators/promotions/campaigns/list

Request ListPromotionCampaignsRequest:

Response data: items as PromotionCampaign[] and nextCursor as string/null.

Campaign detail — /game-operators/promotions/campaigns/detail

Request GetPromotionCampaignRequest:

Response data: campaign as PromotionCampaign.

Cancel campaign — /game-operators/promotions/campaigns/cancel

Request CancelPromotionCampaignRequest:

Response data: campaign as PromotionCampaign, and cancelled as boolean.

8.6 Player assignment endpoints

Add players — /game-operators/promotions/campaigns/players/add

Request AddPromotionPlayersRequest:

Response data:

Remove players — /game-operators/promotions/campaigns/players/remove

Request RemovePromotionPlayersRequest:

Response data:

List player state — /game-operators/promotions/campaigns/players/list

Request ListPromotionPlayersRequest:

Response data: items as PromotionPlayerState[] and nextCursor as string/null.

8.7 Catalog and reporting endpoints

Reward values — /game-operators/promotions/catalog/reward-values

Request GetPromotionRewardValuesRequest:

Response data:

Campaign winners — /game-operators/promotions/reports/winners

Request ListPromotionWinnersRequest:

Response data: items as PromotionWinner[] and nextCursor as string/null.

Leaderboard — /game-operators/promotions/reports/leaderboard

Request GetPromotionLeaderboardRequest: traceId as UUID string, campaignId as string, and optional limit integer. Response data contains campaignId and entries as LeaderboardEntry[].

Prizes — /game-operators/promotions/reports/prizes

Request GetPromotionPrizesRequest: traceId as UUID string, campaignId as string, and optional currencyList as string[]. Response data contains campaignId and prizes as object array.

Report detail — /game-operators/promotions/reports/detail

Request GetPromotionReportDetailRequest: traceId as UUID string and campaignId as string. Response data contains campaign as PromotionCampaign and summary as object.

Reporting row DTOs:

8.8 Jackpot endpoints

Jackpot endpoints are read-only. They do not require requestId, and retries are safe.

Active jackpots — /game-operators/promotions/jackpots/active

Request ListActiveJackpotsRequest:

Response data: items as JackpotPool[] and nextCursor as string/null.

Jackpot winners — /game-operators/promotions/jackpots/winners

Request ListJackpotWinnersRequest:

Response data: items as JackpotWinner[] and nextCursor as string/null.

Validation:

• endTimepoint must be greater than startTimepoint.
• Prosper may cap the maximum time window. If capped, return SC_INVALID_TIME_RANGE.

Jackpot winnings — /game-operators/promotions/jackpots/winnings

Request GetJackpotWinningsRequest:

Response data:

Jackpot contributions — /game-operators/promotions/jackpots/contributions

Request ListJackpotContributionsRequest:

Response data: items as JackpotContribution[] and nextCursor as string/null.

8.9 Promotion and jackpot idempotency

• Mutating promotion requests must include requestId.
• Prosper dedupes by (operatorId, route, requestId).
• Exact replay returns the original response.
• Same requestId with a different payload returns SC_DUPLICATE_REQUEST.
• Player assignment is idempotent per (operatorId, campaignId, playerId, requestId).
• A bulk assignment may partially succeed. The response includes success, already-processed, and failed arrays so the operator can retry only failed players.
• Jackpot list/report routes are read-only and do not require requestId.

8.10 Promotion and jackpot examples

Create a free-spins campaign:

{
  "traceId": "00000000-0000-4000-8000-000000000101",
  "requestId": "promo-create-001",
  "campaignId": "fs-2026-05-operator-a",
  "promotionType": "FREE_SPINS",
  "vendorCode": "vendor-demo",
  "gameList": ["game-001"],
  "currencyList": ["USD"],
  "startAt": 1779436800,
  "expiresAt": 1779840000,
  "validUntil": 1779840000,
  "reward": {
    "rounds": 10,
    "betValues": [
      {
        "currency": "USD",
        "totalBet": 1
      }
    ]
  }
}

Assign players to a campaign:

{
  "traceId": "00000000-0000-4000-8000-000000000102",
  "requestId": "promo-assign-001",
  "campaignId": "fs-2026-05-operator-a",
  "players": [
    {
      "playerId": "john.doe",
      "currency": "USD"
    }
  ]
}

Query reward values:

{
  "traceId": "00000000-0000-4000-8000-000000000103",
  "promotionType": "FREE_CHIPS",
  "vendorCode": "vendor-demo",
  "gameList": ["game-001"],
  "currencyList": ["USD", "EUR"]
}

Query active jackpots:

{
  "traceId": "00000000-0000-4000-8000-000000000104",
  "vendorCode": "vendor-demo",
  "currency": "USD",
  "limit": 100
}

Query jackpot winners:

{
  "traceId": "00000000-0000-4000-8000-000000000105",
  "jackpotId": "jp-main-usd",
  "currency": "USD",
  "startTimepoint": 1779436800,
  "endTimepoint": 1779523200,
  "limit": 100
}

8.11 Promotion contract boundary

The operator should not need to know which upstream adapter handles a campaign or jackpot report. Prosper owns that routing behind this unified API.

9. Credentials

Prosper provides one active credential pair per integration environment:

Credential rules:

• Keep separate credentials per environment.
• Treat secretKey as write-only after provisioning.
• Rotate credentials before disabling an old key.
• Sign every unified aggregator request with the active credential pair.
• Verify every aggregator-to-wallet callback using the configured wallet secret rule in Section 3.2.

10. Unified integration checklist

1. Configure operator record and callback URL.
2. Create an API key and store publicKey plus one-time secretKey.
3. Implement wallet endpoints exactly once for all game vendors.
4. Verify HMAC in both directions, including the sk_ prefix difference.
5. Enforce idempotency by (operatorId, transactionId).
6. Provision players and currency wallets before launch.
7. Pull vendors and games from /game/vendors and /game/list.
8. Launch games using /game/url.
9. Process balance, bet, result, rollback, and adjustment callbacks.
10. Reconcile transactions using /transaction/list and /transaction/detail.
11. Integrate free-spins, free-chips, promotion, and jackpot routes only through /game-operators/promotions/*.
12. Pass negative tests for invalid signature, missing player, wrong currency, insufficient funds, duplicate transaction, rollback missing original, duplicate promotion request, invalid campaign, and invalid jackpot time range.

11. Minimal examples

11.1 Signed game list request

Body:

{
  "traceId": "00000000-0000-4000-8000-000000000010",
  "vendorCode": "vendor-demo",
  "pageNo": 1,
  "pageSize": 100,
  "currency": "USD"
}

Headers:

Content-Type: application/json
Accept: application/json
X-API-Key: pk_example
X-Signature: lowercase_hex_hmac_sha256(secretKey, compact_json_body)

11.2 Wallet bet callback

Request from aggregator to operator:

{
  "traceId": "00000000-0000-4000-8000-000000000001",
  "username": "john.doe",
  "currency": "USD",
  "amount": "10.00",
  "transactionId": "bet-123",
  "roundId": "round-123",
  "gameCode": "game-001",
  "token": "session-token"
}

Response from operator:

{
  "traceId": "00000000-0000-4000-8000-000000000001",
  "status": "SC_OK",
  "data": {
    "transactionId": "bet-123",
    "balance": 90,
    "cashBalance": 80,
    "bonusBalance": 10,
    "usedPromo": 0
  }
}

12. Contract boundary

Only the APIs listed in this guide are part of the operator integration contract. New functionality should appear through one of these unified surfaces before an operator relies on it:

• Catalog and launch: /game-operators/game/vendors, /game-operators/game/list, /game-operators/game/url.
• Money movement: the operator wallet callback API.
• Reconciliation: /game-operators/transaction/list and /game-operators/transaction/detail.
• Free-spins, free chips, promotions, and jackpots: /game-operators/promotions/*.