Integration guide

Partner postback API

Send level-completion events from your game so the reward app can queue coin credits. Use the same pid, uid, and gid values that were attached to the Play install link.

POST/api/postback

Overview

When a player installs your game from a reward app, the Play Store URL carries an install referrer with attribution fields. As the player progresses, your game POSTs level completions to this endpoint. The server validates the payload, enqueues a row in user_postbacks, and the reward app applies coins locally.

Every valid level is recorded.
Coin credit applies only on milestone levels (every 5th level).
The same user + game + level is accepted only once.

Install referrer

The Play listing URL includes a referrer query parameter. URL-decoded, it contains exactly three keys:

Decoded referrer

pid=cashgiraffe&uid=a1b2c3d4-e5f6-7890-abcd-ef1234567890&gid=my_game

On the Play URL this is a single encoded param, for example &referrer=pid%3Dcashgiraffe%26uid%3D…%26gid%3Dmy_game. Your game should read these values at startup and send them unchanged in every postback.

Authentication

All requests must include the shared API secret we provide. Send it using either header:

Headers

Authorization: Bearer <REWARD_API_SECRET>
# or
X-Reward-Api-Secret: <REWARD_API_SECRET>

Endpoint

HTTP request

POST /api/postback
Content-Type: application/json
Authorization: Bearer <REWARD_API_SECRET>

{
  "pid": "cashgiraffe",
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "gid": "my_game",
  "level_number": 10
}

cURL

curl -X POST https://<your-host>/api/postback \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <REWARD_API_SECRET>" \
  -d '{
    "pid": "cashgiraffe",
    "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "gid": "my_game",
    "level_number": 10
  }'

Request body

JSON object. Snake_case is preferred; listed aliases are also accepted.

Field	Type	Required	Description
`pid`	string	Yes	Partner / product id from the Play install referrer. Must match a registered store_apps.pid.
`uid` userId, user_id	uuid	Yes	Reward user id from the install referrer. Must exist in users.id.
`gid` game_id, gameId	string	Yes	Game id from the install referrer. Must exist in reward_games.id.
`level_number` level	integer	Yes	Completed in-game level (positive integer). Stored for every postback; coins are credited only on milestone levels.
`reason`	string	No	Optional free-text note stored in postback metadata.

Milestone rewards

Post any completed level. Coin credit is applied only when level_number is a milestone: every 5th level (5, 10, 15, 20, …). Non-milestone levels are still stored with awarded: false and zero coin delta.

Level range	Coins (milestone only)
1 – 30	25
31 – 70	15
71 – 90	10
91 – 100	5
101 – 130	2
131+	1

Responses

Successful milestone postback:

200 OK — milestone credited

{
  "ok": true,
  "awarded": true,
  "milestone": true,
  "pid": "cashgiraffe",
  "gid": "my_game",
  "game_id": "my_game",
  "level_number": 10,
  "coinDelta": 25,
  "user": { "id": "…", "coins": 125, "appId": "…", "deviceId": "…" }
}

Duplicate postback (same user, game, and level):

200 OK — duplicate

{
  "ok": true,
  "awarded": false,
  "duplicate": true,
  "pid": "cashgiraffe",
  "gid": "my_game",
  "level_number": 10,
  "message": "Duplicate postback for this user, game, and level"
}

Legacy paths

Older integrations may still call /api/reward/postback or /api/rewards/postback. Those URLs permanently redirect (308) to /api/postback and preserve the HTTP method and request body.

Errors

Status	When
401	Missing or invalid API secret.
400	Invalid JSON, missing fields, unknown gid (not in reward_games), or unknown pid (not in store_apps).
404	No user found for the given uid.
200	Duplicate postback for the same user, game, and level (idempotent; awarded: false).

Before going live, register your game id in the reward games catalog and ensure your partner pid is configured on a store app.

Need access?

API secrets and catalog setup are managed through the admin dashboard.