Overview

View as Markdown

Wuzzlo Integration Collection

This documentation is the implementation guide and API contract for wallet operators integrating Wuzzlo games. Start with the integration quickstart, then complete operator onboarding and build the wallet API.

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:

{
  "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.

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.