> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.wuzzlo.com/wuzzlo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.wuzzlo.com/_mcp/server.

# Overview

# Wuzzlo Integration Collection

This documentation is the implementation guide and API contract for wallet operators integrating Wuzzlo games. Start with the [integration quickstart](/integration-quickstart), then complete [operator onboarding](/operator-onboarding) and [build the wallet API](/wallet-api-guide).

## Default staging topology

* Player web: `https://test.wuzzlo.com`
* Operator/integrator facade: `https://sapi.wuzzlo.com`
* Wuzzlo GameService API: `https://vapi.wuzzlo.com`

You can override the collection variables to target production or local environments.

## Main flow

1. Frontend calls `POST /launch-game` on the integrator facade.
2. The integrator signs and forwards the request to Wuzzlo `POST /api/operator/login`.
3. Wuzzlo creates the session and returns a playable game URL.
4. During gameplay Wuzzlo calls the operator wallet APIs: `/balance`, `/betrequest`, `/resultrequest`, and `/rollbackrequest`.
5. If a wallet callback outcome is ambiguous, the operator can reconcile with `get-bet-info` or `get-market-result`.

## Security

* Production requests use RSA-SHA256 over the raw JSON body in the `Signature` header.
* Use PKCS#1 v1.5 padding and verify the exact UTF-8 bytes received on the wire. Parsing and reserializing JSON before verification can change whitespace or property order and invalidate the signature.
* Verify the Wuzzlo signature before creating wallet transactions, idempotency records, or changing a balance.
* `X-Request-Id` should be unique per launch request.
* Wallet operations must be idempotent by `transactionId`.
* Signed folders in this collection auto-generate the `Signature` header in a pre-request script using `jsrsasign` via `pm.require`.
* Postman app, collection runner, monitors, and Postman CLI support external packages. Newman does not.

## Invalid Wuzzlo signature

Every Wuzzlo-to-operator wallet endpoint must reject a missing or invalid `Signature` header with exactly:

```json
{
  "balance": 0,
  "status": "OP_INVALID_SIGNATURE"
}
```

Return HTTP `200`. Do not create transaction or idempotency records, and do not change the user's actual wallet balance. `OP_SUCCESS`, an alternative error status, or a non-`200` HTTP response fails certification for this scenario.

> **Warning**
>
> Do not bypass signature validation in a certification or production environment. A debug bypass can make the normal wallet scenarios pass while the security scenario fails.

## How wallet certification verifies this

The backoffice certification runner performs the following checks against the operator's configured wallet base URL:

1. It sends correctly signed authentication and wallet requests using the Wuzzlo private key.
2. It signs a normal `/balance` payload and then corrupts one byte of the generated RSA signature.
3. It expects HTTP `200`, returned status `OP_INVALID_SIGNATURE`, and returned balance `0` for that request.
4. It immediately sends a correctly signed `/balance` request and verifies that the funded test user's actual balance is unchanged.

The certification report records the tested base URL, request payload, HTTP status, expected return status, returned status, expected balance, returned balance, response payload, and duration. Each scenario has only one valid returned status.

## Docs

- [Integration quickstart](https://docs.wuzzlo.com/integration-quickstart.md): Connect an operator wallet and launch the first Wuzzlo game
- [Operator onboarding](https://docs.wuzzlo.com/operator-onboarding.md): Registration data, environments, keys, and activation
- [Build the wallet API](https://docs.wuzzlo.com/wallet-api-guide.md): Implement the endpoints called by Wuzzlo
- [Settlement and recovery](https://docs.wuzzlo.com/settlement-and-recovery.md): Automatic results, retries, rollback, and reconciliation
- [Security and certification](https://docs.wuzzlo.com/security-and-certification.md): Signing, verification, test scenarios, and production approval

## API Docs

- [Create a Wuzzlo game session](https://docs.wuzzlo.com/wuzzlo/operator-to-wuzzlo/create-a-wuzzlo-game-session.md): Wuzzlo > Operator to Wuzzlo
- [Get paginated game catalog](https://docs.wuzzlo.com/wuzzlo/operator-to-wuzzlo/get-paginated-game-catalog.md): Wuzzlo > Operator to Wuzzlo
- [Get settlement details for one transaction](https://docs.wuzzlo.com/wuzzlo/operator-to-wuzzlo/get-settlement-details-for-one-transaction.md): Wuzzlo > Operator to Wuzzlo
- [Get market or round settlement view](https://docs.wuzzlo.com/wuzzlo/operator-to-wuzzlo/get-market-or-round-settlement-view.md): Wuzzlo > Operator to Wuzzlo
- [Authenticate a player session](https://docs.wuzzlo.com/wuzzlo/wuzzlo-to-operator/authenticate-a-player-session.md): Wuzzlo > Wuzzlo to Operator
- [Get player balance](https://docs.wuzzlo.com/wuzzlo/wuzzlo-to-operator/get-player-balance.md): Wuzzlo > Wuzzlo to Operator
- [Debit player balance for a bet](https://docs.wuzzlo.com/wuzzlo/wuzzlo-to-operator/debit-player-balance-for-a-bet.md): Wuzzlo > Wuzzlo to Operator
- [Credit or settle a bet result](https://docs.wuzzlo.com/wuzzlo/wuzzlo-to-operator/credit-or-settle-a-bet-result.md): Wuzzlo > Wuzzlo to Operator
- [Rollback an unpaid debit](https://docs.wuzzlo.com/wuzzlo/wuzzlo-to-operator/rollback-an-unpaid-debit.md): Wuzzlo > Wuzzlo to Operator

## OpenAPI Specification

- [OpenAPI JSON](https://docs.wuzzlo.com/openapi.json): raw OpenAPI 3.1 specification for this API, JSON format
- [OpenAPI YAML](https://docs.wuzzlo.com/openapi.yaml): raw OpenAPI 3.1 specification for this API, YAML format