Provider Integration Guide

Name	Value
Transport	HTTPS, JSON request bodies, HMAC SHA-256 request signing.
Provider implements	Catalog, launch, and promotion action endpoints.
Provider calls	Prosper wallet and promotion event callbacks.

All examples use placeholder URLs and credentials. Prosper supplies the real base URLs, public keys, shared secrets, provider code, operator scope, site code, and environment for each integration.

1. Overview

Use this guide to implement the Prosper provider integration endpoints and callbacks.

1.1 Integration scope

Prosper configures one integration record per provider, operator, site, and environment.

Field	Meaning
`providerCode`	Stable lowercase provider identifier used in Prosper routes and records.
`operatorId`	Prosper operator UUID. Prosper sends this in provider-pull requests.
`siteCode`	Site or brand scope. Default is `default`.
`environment`	Environment scope such as `staging` or `production`.
`apiBaseUrl`	Provider base URL used by Prosper for catalog, launch, and promotion actions.
`publicKey` and `secret`	Per-integration HMAC credentials. Do not reuse secrets across environments.

1.2 Traffic directions

Direction	Authentication	Purpose
Prosper to provider	`X-Axis-*` HMAC headers	Catalog pull, launch, promotion offers, campaigns, grants, jackpot reports, and tournament reports.
Provider to Prosper	`X-Provider-*` HMAC headers	Wallet authenticate, balance, debit, credit, debit-credit, rollback, adjustment, session terminate, and promotion event callbacks.

1.3 Integration steps

Receive providerCode, operatorId, siteCode, environment, Prosper callback base URL, public key, shared secret, and configured provider paths from Prosper.
Implement the Prosper-to-provider endpoints for the selected capability profile.
Verify every Prosper-to-provider request with X-Axis-* headers.
Call Prosper wallet and promotion event endpoints with X-Provider-* headers.
Use the DTOs, response envelopes, retry rules, and idempotency keys defined in this guide.

1.4 Capability profiles

Profile	Required capabilities
`core`	Catalog, launch, wallet authenticate, balance, debit, credit, debit-credit, rollback, adjustment, session terminate, auth failure handling, nonce replay rejection, invalid amount rejection, and duplicate transaction idempotency.
`promotions`	Everything in `core`, plus offers list, campaign create/cancel, grant create/cancel, and provider promotion event callback.
`full`	Everything in `promotions`, plus jackpot and tournament reports.

1.5 JSON rules

All request and response bodies are JSON.
All timestamps are ISO 8601 strings with an offset, for example 2026-06-03T12:00:00.000Z.
traceId is a UUID used for tracing. Echo it in provider-to-Prosper callback bodies.
Money amounts sent to Prosper are decimal strings, not numbers.
Wallet amounts must be greater than zero and have up to 6 decimal places.
Currency codes are uppercase strings, 3 to 6 characters.
Provider-specific data belongs in metadata, payload, or providerConfig.
Providers must ignore unknown JSON fields sent by Prosper.
Provider-to-Prosper callback DTOs are strict. Do not send extra top-level fields outside the documented DTOs.

1.6 Base paths

Path type	Value
Provider-to-Prosper base	Prosper callback base URL supplied by Prosper for each environment.
Catalog path	Provider path configured in Prosper. Default: `/catalog/games`.
Launch path	Provider path configured in Prosper. Default: `/launch`.
Promotion base path	Provider path configured in Prosper. Default: `/promotions`.

Prosper will provide the exact callback base URL for each environment.

2. Authentication

Both traffic directions use HMAC SHA-256 over the exact raw request body sent on the wire.

2.1 Signature algorithm

Signature payload:

text

{timestamp}.{nonce}.{rawBody}

Signature output:

text

hex(hmac_sha256(sharedSecret, signaturePayload))

Node.js signing example:

javascript

import { createHmac, timingSafeEqual } from "node:crypto";

function sign(secret, timestamp, nonce, rawBody) {
  return createHmac("sha256", secret)
    .update(`${timestamp}.${nonce}.${rawBody}`)
    .digest("hex");
}

function signaturesMatch(expectedHex, actualHex) {
  const expected = Buffer.from(expectedHex, "hex");
  const actual = Buffer.from(actualHex, "hex");
  return expected.length === actual.length && timingSafeEqual(expected, actual);
}

Use the raw body bytes/string exactly as received. Do not verify against a parsed and re-serialized object unless it is guaranteed to be byte-for-byte identical.

2.2 Prosper to provider headers

Prosper signs every provider-pull request with these headers:

Header	Meaning
`X-Axis-Provider-Key`	Public key for the integration.
`X-Axis-Timestamp`	ISO timestamp generated by Prosper.
`X-Axis-Nonce`	Unique nonce generated by Prosper.
`X-Axis-Signature`	Hex HMAC SHA-256 signature.

Provider requirements:

Verify the public key maps to the expected integration.
Reject timestamps outside a 5 minute window.
Reject replayed nonces inside the timestamp window.
Compare signatures using a timing-safe comparison.
Return HTTP 401 for invalid credentials, stale timestamp, replayed nonce, or invalid signature.

2.3 Provider to Prosper headers

Providers must sign every callback to Prosper with:

Header	Meaning
`X-Provider-Key`	Public key Prosper issued for this integration.
`X-Provider-Timestamp`	ISO timestamp generated by provider.
`X-Provider-Nonce`	Unique nonce, 8 to 128 characters.
`X-Provider-Signature`	Hex HMAC SHA-256 signature.

Prosper validation rules:

Timestamp tolerance is 5 minutes.
Nonce must be unique per integration inside the timestamp window.
Integration must be enabled and the callback base URL must match the public key.
If an IP allowlist is configured, the request IP must match exactly.
Authentication failures return HTTP 401.
Validation failures return HTTP 400.

2.4 Signed callback example

http

POST {prosperCallbackBaseUrl}/wallet/balance
Content-Type: application/json
Accept: application/json
X-Provider-Key: gpk_staging_acme
X-Provider-Timestamp: 2026-06-03T12:00:00.000Z
X-Provider-Nonce: 6e8e4a2b-9468-4b7d-b66c-85d7c12e7568
X-Provider-Signature: 1ec8d8ab...

json

{
  "traceId": "4090b86e-15fd-497a-9fa4-795e98dc8472",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-123",
  "currency": "USD"
}

3. Prosper to provider endpoints

Prosper sends POST requests to the provider base URL configured for the integration. Prosper signs every request with X-Axis-* headers.

Provider responses may be an envelope with data or the raw data object directly. Prosper unwraps data when present. HTTP non-2xx responses are treated as failed provider requests.

3.1 Catalog games

Default path: POST /catalog/games

Prosper request:

Field	Required	Description
`traceId`	Yes	UUID for this request.
`providerCode`	Yes	Provider code configured in Prosper.
`operatorId`	Yes	Prosper operator UUID.
`siteCode`	Yes	Site scope for the integration.
`environment`	Yes	Environment scope for the integration.
`query`	Yes	Original Prosper game-list query. Providers should ignore unknown fields.

Sample request:

json

{
  "traceId": "4f2b4817-e7dd-45aa-9f29-d210cf72e675",
  "providerCode": "acme-games",
  "operatorId": "5d7778e2-e86f-4173-9e11-7f0f3d23227e",
  "siteCode": "default",
  "environment": "staging",
  "query": {
    "traceId": "4f2b4817-e7dd-45aa-9f29-d210cf72e675",
    "vendorCode": "acme-games",
    "pageNo": 1,
    "pageSize": 100,
    "currency": "USD",
    "fetchFromApi": true
  }
}

Game DTO:

Field	Required	Description
`gameCode`	Yes	Stable provider game code.
`gameName`	Yes	Display name.
`categoryCode`	Yes	Category code such as `slots`, `live`, `table`.
`languageCodes`	No	Supported language codes.
`platformCodes`	No	Supported platforms such as `WEB`, `MOBILE`.
`currencyCodes`	No	Supported currency codes.
`isOpen`	No	Whether the game is open for play.
`isAvailable`	No	Whether the game is available for this integration.
`isVip`	No	Whether the game is VIP-only.
`rtp`	No	RTP value as string or number.
`volatility`	No	Provider volatility label.
`imageSquare`	No	Square image URL.
`imageWide`	No	Wide image URL.
`imageLandscape`	No	Landscape image URL.
`imagePortrait`	No	Portrait image URL.
`imageStandard`	No	Standard image URL.
`vendorCode`	No	Provider/vendor code.
`vendorName`	No	Provider/vendor display name.
`availabilityUpdatedAt`	No	ISO timestamp or null.
`metadata`	No	Provider-specific JSON object.

Sample response:

json

{
  "status": "OK",
  "message": "Successful response.",
  "data": {
    "games": [
      {
        "gameCode": "acme-slot-100",
        "gameName": "Acme Slot 100",
        "categoryCode": "slots",
        "languageCodes": ["en"],
        "platformCodes": ["WEB", "MOBILE"],
        "currencyCodes": ["USD", "EUR"],
        "isOpen": true,
        "isAvailable": true,
        "rtp": "96.50",
        "vendorCode": "acme-games",
        "vendorName": "Acme Games",
        "metadata": {}
      }
    ]
  }
}

3.2 Launch

Default path: POST /launch

Prosper creates a session token first, then sends it to the provider. Providers should bind their playable session to sessionToken; wallet callbacks should prefer this token for session lookup.

Field	Required	Description
`traceId`	Yes	UUID for launch.
`sessionToken`	Yes	Prosper session token. Prefer this in wallet callbacks.
`operatorId`	Yes	Prosper operator UUID.
`providerCode`	Yes	Provider code.
`siteCode`	Yes	Site scope.
`environment`	Yes	Environment scope.
`username`	Yes	Player username.
`nickname`	No	Player nickname.
`subOperator`	No	Sub-operator or brand reference.
`gameCode`	Yes	Provider game code.
`currency`	Yes	Currency code.
`language`	Yes	Language code.
`platform`	Yes	Platform code.
`playMode`	No	`REAL` or `DEMO`.
`lobbyUrl`	Yes	URL to return the player to the operator lobby.
`depositUrl`	No	Deposit URL.
`country`	No	Player country or market.
`ipAddress`	Yes	Player IP address passed by operator.
`playerType`	No	`VIP` or `TEST`.

Sample request:

json

{
  "traceId": "8e89d29d-7d89-4637-9696-4c68c17fae70",
  "sessionToken": "6f628e10-b229-4279-b7f4-aa8139d7488e",
  "operatorId": "5d7778e2-e86f-4173-9e11-7f0f3d23227e",
  "providerCode": "acme-games",
  "siteCode": "default",
  "environment": "staging",
  "username": "player123",
  "nickname": "Player 123",
  "gameCode": "acme-slot-100",
  "currency": "USD",
  "language": "en",
  "platform": "WEB",
  "playMode": "REAL",
  "lobbyUrl": "https://operator.example/lobby",
  "depositUrl": "https://operator.example/deposit",
  "country": "US",
  "ipAddress": "203.0.113.10",
  "playerType": "TEST"
}

Launch response DTO:

Field	Required	Description
`launchUrl`	Yes	URL Prosper returns to the operator for the player to open.
`providerSessionId`	No	Provider session id. If returned, Prosper stores it for future callbacks.
`clientSessionId`	No	Optional provider/client session reference.
`clientPlayerId`	No	Optional provider/client player reference.
`username`	No	Optional normalized username.
`metadata`	No	Provider-specific JSON object.

Sample response:

json

{
  "status": "OK",
  "data": {
    "launchUrl": "https://provider.example/play?token=6f628e10-b229-4279-b7f4-aa8139d7488e",
    "providerSessionId": "gps-20260603-10001",
    "clientSessionId": "client-session-1",
    "clientPlayerId": "client-player-123",
    "username": "player123",
    "metadata": {}
  }
}

3.3 Promotion actions

Default promotion base path: /promotions

Promotion endpoints are required for the promotions and full profiles.

Path	Purpose
`/promotions/offers/list`	Return provider promotion offers that Prosper can store and expose to operators.
`/promotions/campaigns/create`	Create or activate a campaign at the provider.
`/promotions/campaigns/cancel`	Cancel a campaign at the provider.
`/promotions/grants/create`	Grant a promotion to a player.
`/promotions/grants/cancel`	Cancel a player grant.
`/promotions/reports/jackpots`	Return jackpot report data. Required for `full`.
`/promotions/reports/tournaments`	Return tournament report data. Required for `full`.

Offers list

Request:

json

{
  "traceId": "386917ad-6db7-418e-9e4e-a142e59c8818",
  "providerCode": "acme-games",
  "operatorId": "5d7778e2-e86f-4173-9e11-7f0f3d23227e",
  "siteCode": "default",
  "environment": "staging"
}

Offer response fields:

Field	Required	Description
`id`	No	Provider offer id. Used as fallback for `providerOfferRef`.
`type`	No	Promotion type. Defaults to `provider_specific`. Supported values are listed below.
`providerOfferRef`	No	Stable provider offer reference.
`scope`	No	JSON object describing scope, such as games, brands, currencies, or markets.
`reward`	No	JSON object describing reward, such as spins, bet amount, bonus amount, or jackpot config.
`offerHash`	No	Provider hash/version. Prosper can store it when present.
`expiresAt`	No	ISO timestamp after which the offer is unavailable.
`configSchema`	No	JSON schema or free-form config definition for operator/provider config.
`available`	No	Defaults to `true` unless explicitly `false`.
`unavailableReason`	No	Reason when unavailable.
`metadata`	No	Provider-specific JSON object.

Supported promotion type values:

text

free_bet, bonus_money, bonus_game, free_chips, tournament, prize_drop,
jackpot, cashback, deposit_bonus, welcome_bonus, provider_specific

Sample response:

json

{
  "status": "OK",
  "data": {
    "offers": [
      {
        "id": "offer-free-spins-10",
        "type": "free_bet",
        "providerOfferRef": "fs10-usd-web",
        "scope": { "games": ["acme-slot-100"], "currencies": ["USD"] },
        "reward": { "spins": 10, "betAmount": "0.10" },
        "configSchema": { "type": "object", "additionalProperties": true },
        "available": true,
        "metadata": {}
      }
    ]
  }
}

Promotion request object fields

Promotion action requests include full Prosper promotion objects. Providers should validate the fields they use and ignore unknown nested fields.

Action path	Request body fields
`/promotions/offers/list`	`traceId`, `providerCode`, `operatorId`, `siteCode`, `environment`.
`/promotions/campaigns/create`	`traceId`, `offer`, `campaign`, `providerConfig`.
`/promotions/campaigns/cancel`	`traceId`, `campaign`.
`/promotions/grants/create`	`traceId`, `campaign`, `grant`, `providerConfig`.
`/promotions/grants/cancel`	`traceId`, `campaign`, `grant`.
`/promotions/reports/jackpots`	Operator report payload plus `traceId`.
`/promotions/reports/tournaments`	Operator report payload plus `traceId`.

Offer object — sent in /promotions/campaigns/create:

Field	JSON value	Description
`id`	UUID string	Prosper offer id.
`createdAt`	ISO timestamp string	Offer creation time.
`updatedAt`	ISO timestamp string	Last offer update time.
`operatorId`	UUID string	Prosper operator id.
`type`	string	Promotion type. Values are listed above.
`providerCode`	string	Provider code configured in Prosper.
`scope`	object	Eligible scope such as games, currencies, brands, markets, or player segments.
`reward`	object	Reward definition such as spins, bet amount, bonus amount, jackpot config, or provider-specific reward data.
`providerOfferRef`	string or null	Stable provider offer reference.
`offerHash`	string	Prosper offer version/hash.
`expiresAt`	ISO timestamp string or null	Offer expiry time.
`configSchema`	object	Provider/operator configuration schema or free-form config definition.
`available`	boolean	Whether the offer can be used for new campaigns.
`unavailableReason`	string or null	Reason when `available` is false.
`rawProviderResponse`	JSON value or null	Original provider offer item stored by Prosper.
`metadata`	object	Provider-specific metadata stored with the offer.

Campaign object — sent with /promotions/campaigns/create, /promotions/campaigns/cancel, /promotions/grants/create, and /promotions/grants/cancel:

Field	JSON value	Description
`id`	UUID string	Prosper campaign id.
`createdAt`	ISO timestamp string	Campaign creation time.
`updatedAt`	ISO timestamp string	Last campaign update time.
`offerId`	UUID string	Prosper offer id used to create the campaign.
`operatorId`	UUID string	Prosper operator id.
`type`	string	Promotion type. Values are listed above.
`name`	string	Campaign display name, max 160 chars.
`status`	string	Campaign status. Values: `draft`, `validating`, `scheduled`, `active`, `processing`, `cancelled`, `expired`, `failed`, `partial`.
`operatorReference`	string or null	Operator campaign reference.
`providerCode`	string	Provider code configured in Prosper.
`providerCampaignRef`	string or null	Provider campaign reference returned by provider. Null before the provider creates the campaign.
`providerStatus`	string or null	Provider campaign status returned by provider.
`providerRawResponse`	JSON value or null	Last raw provider response stored for this campaign.
`scope`	object	Campaign scope. If the operator sends an empty object, Prosper uses the offer scope.
`reward`	object	Campaign reward. If the operator sends an empty object, Prosper uses the offer reward.
`schedule`	object	Original schedule object from the operator request. May include `startsAt`, `endsAt`, and `timezone`.
`startsAt`	ISO timestamp string or null	Parsed campaign start time.
`endsAt`	ISO timestamp string or null	Parsed campaign end time.
`providerConfig`	object	Provider-specific campaign configuration.
`idempotencyKey`	string or null	Operator idempotency key for campaign creation.
`metadata`	object	Campaign metadata.

Grant object — sent in /promotions/grants/create and /promotions/grants/cancel:

Field	JSON value	Description
`id`	UUID string	Prosper grant id.
`createdAt`	ISO timestamp string	Grant creation time.
`updatedAt`	ISO timestamp string	Last grant update time.
`campaignId`	UUID string	Prosper campaign id.
`operatorId`	UUID string	Prosper operator id.
`providerCode`	string	Provider code configured in Prosper.
`status`	string	Grant status. Values: `pending`, `processing`, `active`, `used`, `finished`, `expired`, `cancelled`, `failed`.
`playerId`	UUID string or null	Prosper player id when available.
`playerUsername`	string	Player username, max 128 chars.
`playerExternalId`	string or null	Operator/player external id when supplied.
`operatorGrantReference`	string or null	Operator grant reference.
`providerGrantRef`	string or null	Provider grant reference returned by provider. Null before the provider creates the grant.
`providerStatus`	string or null	Provider grant status returned by provider.
`providerRawResponse`	JSON value or null	Last raw provider response stored for this grant.
`rewardSnapshot`	object	Reward assigned to this player. If the operator does not override reward, Prosper uses the campaign reward.
`usedCount`	integer	Number of consumed reward units recorded by Prosper.
`remainingCount`	integer or null	Remaining reward count when Prosper can derive it from the reward.
`idempotencyKey`	string or null	Operator idempotency key for grant creation.
`metadata`	object	Grant metadata.

Campaign create

Request:

json

{
  "traceId": "fac5f1d7-d3fd-420a-9427-d384d4c4acc9",
  "offer": {
    "id": "88b7688d-3b81-4d74-b0b7-52bdb80fd049",
    "type": "free_bet",
    "providerCode": "acme-games",
    "providerOfferRef": "fs10-usd-web",
    "scope": { "games": ["acme-slot-100"] },
    "reward": { "spins": 10 },
    "configSchema": {},
    "metadata": {}
  },
  "campaign": {
    "id": "4364c972-39e3-4ce9-98cc-3fb34135fd7c",
    "offerId": "88b7688d-3b81-4d74-b0b7-52bdb80fd049",
    "operatorId": "5d7778e2-e86f-4173-9e11-7f0f3d23227e",
    "type": "free_bet",
    "name": "Weekend Free Spins",
    "status": "active",
    "operatorReference": "promo-2026-06",
    "providerCode": "acme-games",
    "scope": { "games": ["acme-slot-100"] },
    "reward": { "spins": 10 },
    "schedule": {
      "startsAt": "2026-06-03T12:00:00.000Z",
      "endsAt": "2026-06-10T12:00:00.000Z"
    },
    "providerConfig": {},
    "idempotencyKey": "campaign-2026-06",
    "metadata": {}
  },
  "providerConfig": {}
}

Provider response:

json

{
  "status": "OK",
  "message": "Campaign created.",
  "data": {
    "providerCampaignRef": "provider-campaign-10001",
    "providerStatus": "active"
  }
}

Campaign cancel

Request:

json

{
  "traceId": "ec47a2d7-7261-4a2c-bdc0-77ce5f3a6633",
  "campaign": {
    "id": "4364c972-39e3-4ce9-98cc-3fb34135fd7c",
    "providerCode": "acme-games",
    "providerCampaignRef": "provider-campaign-10001",
    "status": "active",
    "metadata": {}
  }
}

Provider response:

json

{
  "status": "OK",
  "data": {
    "providerCampaignRef": "provider-campaign-10001",
    "providerStatus": "cancelled"
  }
}

Grant create

Request:

json

{
  "traceId": "e3f9dc53-f5df-4acd-8705-a99d9de2fe51",
  "campaign": {
    "id": "4364c972-39e3-4ce9-98cc-3fb34135fd7c",
    "providerCampaignRef": "provider-campaign-10001",
    "providerCode": "acme-games",
    "status": "active",
    "reward": { "spins": 10 }
  },
  "grant": {
    "id": "9809f059-ecb5-4462-9a2d-2c7f98e2e888",
    "campaignId": "4364c972-39e3-4ce9-98cc-3fb34135fd7c",
    "operatorId": "5d7778e2-e86f-4173-9e11-7f0f3d23227e",
    "providerCode": "acme-games",
    "status": "active",
    "playerUsername": "player123",
    "playerExternalId": "external-player-123",
    "operatorGrantReference": "grant-2026-06-player123",
    "rewardSnapshot": { "spins": 5 },
    "remainingCount": 5,
    "idempotencyKey": "grant-2026-06-player123",
    "metadata": {}
  },
  "providerConfig": {}
}

Provider response:

json

{
  "status": "OK",
  "data": {
    "providerGrantRef": "provider-grant-20001",
    "providerStatus": "active"
  }
}

Grant cancel

Request:

json

{
  "traceId": "09cf642e-caa1-461c-a1fd-2ce3dc18c53b",
  "campaign": {
    "id": "4364c972-39e3-4ce9-98cc-3fb34135fd7c",
    "providerCampaignRef": "provider-campaign-10001",
    "providerCode": "acme-games"
  },
  "grant": {
    "id": "9809f059-ecb5-4462-9a2d-2c7f98e2e888",
    "providerCode": "acme-games",
    "providerGrantRef": "provider-grant-20001",
    "playerUsername": "player123",
    "status": "active"
  }
}

Provider response:

json

{
  "status": "OK",
  "data": {
    "providerGrantRef": "provider-grant-20001",
    "providerStatus": "cancelled"
  }
}

Jackpot and tournament reports

Prosper forwards the operator report payload plus the current traceId. Providers may return any JSON object useful for reconciliation and display.

Request:

json

{
  "traceId": "03c43944-f7cb-410f-91ec-cae4e3bf1b8b",
  "providerCode": "acme-games",
  "from": "2026-06-01T00:00:00.000Z",
  "to": "2026-06-03T23:59:59.000Z",
  "options": {}
}

Response:

json

{
  "status": "OK",
  "data": {
    "items": [],
    "generatedAt": "2026-06-03T12:00:00.000Z"
  }
}

4. Provider to Prosper endpoints

Prosper provides the callback base URL for each environment. The endpoint paths below are relative to that base URL: {prosperCallbackBaseUrl}.

All provider callbacks must be signed with X-Provider-* headers.

4.1 Response envelope

Successful wallet and event callbacks return HTTP 200 with:

json

{
  "traceId": "1d8eb955-cdc2-4d43-a217-1b8b83fb9eb9",
  "status": "SC_OK",
  "message": "Successful response.",
  "data": {}
}

Validation failures return HTTP 400. Authentication failures return HTTP 401. Wallet business errors usually return HTTP 200 with a non-SC_OK status.

4.2 Wallet status values

Status	Meaning
`SC_OK`	Successful response.
`SC_INSUFFICIENT_FUNDS`	Player balance cannot cover debit.
`SC_ACCOUNT_NOT_FOUND`	Wallet account not found.
`SC_USER_NOT_EXISTS`	Session or user not found.
`SC_WRONG_CURRENCY`	Currency is invalid for the player/account.
`SC_LIMIT_REACHED`	Operator or player limit reached.
`SC_INVALID_OPERATOR`	Operator configuration is invalid or missing.
`SC_INVALID_SIGNATURE`	Wallet downstream signature error. Provider-to-Prosper auth failures still use HTTP 401.
`SC_INVALID_GAME`	Game is invalid.
`SC_INVALID_REQUEST`	Business request is invalid.
`SC_SYSTEM_ERROR`	System error.
`SC_DUPLICATE_TRANSACTION`	Downstream wallet duplicate transaction response. Prosper itself returns stored success for duplicate successful provider transaction ids.
`SC_TRANSACTION_NOT_FOUND`	Transaction not found.
`SC_TRANSACTION_NOT_EXISTS`	Transaction does not exist.

4.3 Common field rules

Field	Rule	Description
`traceId`	UUID	Required in every callback.
`token`	1-512 chars	Preferred session lookup key. Token is sent by Prosper in launch.
`providerSessionId`	1-128 chars	Provider session id. Prosper stores it when returned from launch or authenticate.
`username`	1-128 chars	Session lookup fallback. Requires `currency` when no token/provider session id is sent.
`currency`	3-6 uppercase chars	Required for transactions and username-only lookup.
`amount`	decimal string	Greater than zero, up to 6 decimal places. Examples: `1`, `1.00`, `1.123456`.
`metadata`	object	Optional provider-specific data. Defaults to `{}` when omitted.

Session lookup rule: send token whenever possible. If token is unavailable, send providerSessionId. If both are unavailable, send username and currency.

4.4 Wallet authenticate

Path: POST /wallet/authenticate

Field	Required	Description
`traceId`	Yes	UUID.
`token`	Yes	Prosper session token from launch.
`providerSessionId`	No	Provider session id to store/update on the Prosper session.
`username`	No	Player username.
`currency`	No	Currency code.
`metadata`	No	JSON object.

Request:

json

{
  "traceId": "cbac4edc-7ac2-47d0-97d5-21fd64c69e1f",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "username": "player123",
  "currency": "USD",
  "metadata": {}
}

Success data:

json

{
  "username": "player123",
  "currency": "USD",
  "balance": 100.5,
  "cashBalance": 100.5,
  "bonusBalance": 0,
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1"
}

4.5 Wallet balance

Path: POST /wallet/balance

Request fields are the common lookup fields, traceId, and optional metadata. At least one of token, providerSessionId, or username is required.

json

{
  "traceId": "da66322f-1ff2-45f2-bc5c-4bb76ed3a7b7",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "currency": "USD",
  "metadata": {}
}

Success data is the same as authenticate success data.

4.6 Wallet debit

Path: POST /wallet/debit

Field	Required	Description
`traceId`	Yes	UUID.
`token` / `providerSessionId` / `username`	Yes	Session lookup. Username-only lookup requires `currency`.
`transactionId`	Yes	Provider debit id. Idempotency key, 1-128 chars.
`roundId`	Yes	Provider round id, 1-128 chars.
`gameCode`	Yes	Provider game code, 1-128 chars.
`amount`	Yes	Positive decimal string.
`currency`	Yes	Currency code.
`eventId`	No	Provider event id, 1-128 chars.
`eventTime`	No	ISO timestamp with offset.
`metadata`	No	JSON object.

json

{
  "traceId": "3e25a693-4cb2-424b-b2c2-116c6dc0f12e",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "transactionId": "provider-bet-1",
  "roundId": "round-1",
  "gameCode": "acme-slot-100",
  "amount": "1.00",
  "currency": "USD",
  "eventId": "event-1",
  "eventTime": "2026-06-03T12:00:00.000Z",
  "metadata": {}
}

Success data for debit, credit, debit-credit, rollback, and adjustment:

json

{
  "transactionId": "operator-wallet-transaction-1",
  "balance": 99.5,
  "currency": "USD"
}

4.7 Wallet credit

Path: POST /wallet/credit

Fields are the same as debit, plus:

Field	Required	Description
`isWin`	No	Boolean. Defaults to `true`.

json

{
  "traceId": "b43f39f5-f505-4a1a-8821-85e448a92530",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "transactionId": "provider-win-1",
  "roundId": "round-1",
  "gameCode": "acme-slot-100",
  "amount": "2.00",
  "currency": "USD",
  "isWin": true,
  "metadata": {}
}

4.8 Wallet debit-credit

Path: POST /wallet/debit-credit

Use this endpoint when one provider event contains both bet and result.

Field	Required	Description
`traceId`	Yes	UUID.
`token` / `providerSessionId` / `username`	Yes	Session lookup.
`debitTransactionId`	Yes	Provider debit id.
`creditTransactionId`	Yes	Provider credit id.
`roundId`	Yes	Provider round id.
`gameCode`	Yes	Provider game code.
`debitAmount`	Yes	Positive decimal string.
`creditAmount`	Yes	Positive decimal string.
`currency`	Yes	Currency code.
`eventTime`	No	ISO timestamp with offset.
`metadata`	No	JSON object.

json

{
  "traceId": "72e00c42-bf33-4339-bf80-3d03c950ed3b",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "debitTransactionId": "provider-bet-2",
  "creditTransactionId": "provider-win-2",
  "roundId": "round-2",
  "gameCode": "acme-slot-100",
  "debitAmount": "1.00",
  "creditAmount": "2.00",
  "currency": "USD",
  "eventTime": "2026-06-03T12:00:00.000Z",
  "metadata": {}
}

4.9 Wallet rollback

Path: POST /wallet/rollback

Field	Required	Description
`traceId`	Yes	UUID.
`token` / `providerSessionId` / `username`	Yes	Session lookup. Inactive sessions may still be resolved for rollback.
`transactionId`	Yes	Provider rollback id. Idempotency key.
`originalTransactionId`	Yes	Original provider transaction id to rollback.
`roundId`	Yes	Provider round id.
`gameCode`	Yes	Provider game code.
`amount`	Yes	Positive decimal string.
`currency`	Yes	Currency code.
`metadata`	No	JSON object.

json

{
  "traceId": "6b0bd6b8-84d6-477b-8dc8-0cfc95e73701",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "transactionId": "provider-rollback-1",
  "originalTransactionId": "provider-bet-1",
  "roundId": "round-1",
  "gameCode": "acme-slot-100",
  "amount": "1.00",
  "currency": "USD",
  "metadata": {}
}

4.10 Wallet adjustment

Path: POST /wallet/adjustment

Field	Required	Description
`traceId`	Yes	UUID.
`token` / `providerSessionId` / `username`	Yes	Session lookup. Inactive sessions may still be resolved for adjustment.
`transactionId`	Yes	Provider adjustment id. Idempotency key.
`amount`	Yes	Positive decimal string.
`currency`	Yes	Currency code.
`adjustmentType`	No	`REWARD`, `GIFT`, or `CANCEL_GIFT`. Defaults to `REWARD`.
`adjustmentTime`	No	ISO timestamp with offset. Defaults to current Prosper time.
`originalTransactionId`	No	Original provider transaction/reference if applicable.
`metadata`	No	JSON object.

json

{
  "traceId": "f56666b1-9918-4930-a438-405e03420c75",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "transactionId": "provider-reward-1",
  "amount": "3.00",
  "currency": "USD",
  "adjustmentType": "REWARD",
  "adjustmentTime": "2026-06-03T12:00:00.000Z",
  "metadata": {}
}

4.11 Session terminate

Path: POST /wallet/session/terminate

Field	Required	Description
`traceId`	Yes	UUID.
`token` / `providerSessionId` / `username`	Yes	Session lookup. Username-only lookup requires `currency`.
`currency`	Conditional	Required only for username-only lookup.
`reason`	No	Termination reason, 1-512 chars.

json

{
  "traceId": "d80b7445-0d06-47a9-9407-d15301c433ff",
  "token": "prosper-session-token",
  "providerSessionId": "provider-session-1",
  "reason": "Provider session closed"
}

Success data:

json

{
  "providerSessionId": "provider-session-1"
}

4.12 Promotion event callback

Path: POST /promotions/events

Use this endpoint for provider-originated promotion lifecycle, settlement, jackpot, tournament, grant, or usage events.

Field	Required	Description
`traceId`	Yes	UUID.
`eventType`	Yes	Event type, 1-64 chars. Example: `free_spins.granted`.
`providerRef`	No	Provider event/reference id, 1-256 chars.
`campaignRef`	No	Provider campaign reference, 1-256 chars.
`grantRef`	No	Provider grant reference, 1-256 chars.
`playerUsername`	No	Player username, 1-128 chars.
`payload`	No	Event payload JSON object. Defaults to `{}`.
`occurredAt`	No	ISO timestamp with offset. Defaults to current Prosper time.
`metadata`	No	Provider-specific JSON object. Defaults to `{}`.

json

{
  "traceId": "9d488da2-1d49-4a23-afec-12a32ea1c8c8",
  "eventType": "free_spins.granted",
  "providerRef": "provider-event-30001",
  "campaignRef": "provider-campaign-10001",
  "grantRef": "provider-grant-20001",
  "playerUsername": "player123",
  "payload": {
    "spins": 10,
    "remainingSpins": 10
  },
  "occurredAt": "2026-06-03T12:00:00.000Z",
  "metadata": {}
}

Success data:

json

{
  "accepted": true
}

5. Runtime rules

5.1 Timeouts

Prosper-to-provider HTTP requests use a default timeout of 5000 ms. Providers should target:

Flow	Target
Wallet callbacks to Prosper	Provider should retry only after receiving no response or an ambiguous network failure.
Catalog, launch, promotion actions	Provider should respond within 5 seconds. Faster is preferred for launch.

5.2 Retry and idempotency

Flow	Idempotency key	Expected retry behavior
Catalog	`traceId` for tracing only	Provider may recompute response.
Launch	`sessionToken`	If the same token is received again, provider should return the same playable session when possible.
Debit	`transactionId`	Retry with the same `transactionId` and a new nonce. Prosper returns stored success after first successful debit.
Credit	`transactionId`	Retry with the same `transactionId` and a new nonce. Prosper returns stored success after first successful credit.
Debit-credit	`debitTransactionId`, `creditTransactionId`	Each transaction id is idempotent independently.
Rollback	rollback `transactionId`	Retry with the same rollback id.
Adjustment	`transactionId`	Retry with the same adjustment id.
Promotion actions	Prosper record id or idempotency key in the record	Provider should return existing provider reference/status for duplicate creates or cancels when possible.

Never create a new provider transaction id for the same player action after a timeout. Reuse the original transaction id and sign the retry with a fresh nonce.

5.3 Error handling

Provider-to-Prosper authentication error: Prosper returns HTTP 401.
Provider-to-Prosper validation error: Prosper returns HTTP 400.
Wallet business error: Prosper returns HTTP 200 with non-SC_OK status.
Prosper-to-provider HTTP non-2xx: Prosper treats the action as failed.
Prosper-to-provider malformed JSON: Prosper treats the action as failed.
Prosper-to-provider launch without launchUrl: Prosper treats launch as failed.