Overview & Specs

Official technical specification for integrating with The Ear Platform seamless external wallet service. This documentation details all request/response models, mandatory security signature algorithms, idempotency guarantees, and interactive testing utilities.

Sequence & Protocol

The integration follows a sequential handshake: game session launch is validated by an immediate GetUserInfo call, followed by game rounds consisting of atomic bet debits, win credits, or transaction reversals.

Session Management (sid)

The sid field is a UUID token that uniquely identifies each active session for each player.

Idempotency Model

Network retries must never result in duplicate billing or double credits.

Hash Calculation Formula

Calculate the authentication hash using all request body parameters concatenated with the private key shared with The Ear Platform. All parameters must be URL-encoded without spaces before computing the SHA-256 digest.

SHA256( URLENCODE( COMPACT_JSON_WITHOUT_HASH ) + PRIVATE_KEY )

Live Hash Generator

Paste any payload and private key below to inspect every intermediate transformation of The Ear Platform hash algorithm in real time.

Postman Pre-Request Script

Automate hash generation in Postman using this ready-to-copy Pre-request Script. Store your shared private key in an environment variable named THE_EAR_PRIVATE_KEY.

// Parse current request body
let body = {};
try {
  body = JSON.parse(pm.request.body.raw);
} catch (e) {
  console.error("Invalid JSON body", e);
}

// 1. Remove existing hash if present
delete body.hash;

// 2. Compact JSON string without whitespace
let rawJson = JSON.stringify(body);

// 3. URL-encode string
let urlEncoded = encodeURIComponent(rawJson);

// 4. Retrieve private key and concatenate
let privateKey = pm.environment.get("THE_EAR_PRIVATE_KEY") || "theear_secret_demo_key_2026";
let stringToSign = urlEncoded + privateKey;

// 5. Compute SHA-256 hash using CryptoJS
let calculatedHash = CryptoJS.SHA256(stringToSign).toString();

// 6. Inject hash back into request payload
body.hash = calculatedHash;
pm.request.body.raw = JSON.stringify(body, null, 2);

Endpoints Reference

Comprehensive schema, parameter definitions, and usage examples for all five core endpoints.

{
  "gameId": "gameId",
  "playerId": "6",
  "brandId": "theearplatform_4003",
  "sid": "6370cc15-ee67-4e0f-afaf-a9132c942769",
  "displayName": "4003_6",
  "mobile": false,
  "language": "en",
  "isFreeGame": 0,
  "returnUrl": null,
  "currency": "EUR"
}

{
  "balance": 256.20,
  "message": "OK"
}

{
  "balance": 250.36,
  "transactionId": "56985541",
  "message": "OK"
}

{
  "balance": 500.36,
  "transactionId": "85967123",
  "message": "OK"
}

{
  "balance": 500.36,
  "transactionId": "654654321",
  "message": "OK"
}

HTTP Status Rules

In case of an error in any call, an HTTP status code other than 200 will be returned. Error codes inside the body are not used; the HTTP status code indicates the failure class, and the message field describes the specific cause.

{
  "user_currency": [
    "The user currency field is required."
  ]
}

{
  "message": "User not found"
}

{
  "message": "INVALID HASH"
}

{
  "message": "Session expired"
}

{
  "balance": 10051.31,
  "transactionId": null,
  "message": "Transaction error"
}

{
  "balance": 10051.91,
  "transactionId": null,
  "message": "Transaction with id =D_641738e0-7091-4d3c-b1b0-9dbad5cb8a4c6 doesn’t exists."
}

Testing Console

{
  "balance": 256.20,
  "message": "OK"
}

content-type: application/json; charset=utf-8
x-theear-server: aggregator-sandbox-v1
x-execution-mode: isolated-sandbox
x-request-id: req_init