Wallet and payments

Player wallet #

Access: Player token Header Authorization: Bearer <player token> — issued by SMS sign-in.

Balance in roubles and the last 30 operations: top-ups, bookings, refunds, rentals, shares.

Headers

Example request

curl -X GET "https://your-server/api/v1/wallet" \
  -H "Authorization: Bearer <player token>"

Responses

Example response

{
  "balance": 4200,
  "transactions": [
    {
      "id": "71b3e9d0-5c2a-4e86-9f14-a8d6c3b0e275",
      "amount": 5000,
      "kind": "topup",
      "status": "done",
      "note": "YooKassa payment 2f1a…",
      "at": "2026-10-02T09:12:44+00:00"
    }
  ]
}

Top up the wallet #

Access: Player token Header Authorization: Bearer <player token> — issued by SMS sign-in.

Creates a YooKassa payment and returns confirmationUrl — the payment page to open for the player. Money is credited only after the status is confirmed with YooKassa. The amount is whole roubles within the cloud limits (100–100,000 by default). If online payment is not connected — 503.

Headers

Request body application/json

Example request

curl -X POST "https://your-server/api/v1/wallet/topup" \
  -H "Authorization: Bearer <player token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000}'

Responses

Example response

{
  "ok": true,
  "status": "pending",
  "paymentId": "e4a19c7d-6b3f-4c21-8d5e-0f2a7b9c1d36",
  "confirmationUrl": "https://yoomoney.ru/checkout/payments/v2/contract?orderId=<id>"
}

Top-up payment status #

Access: Player token Header Authorization: Bearer <player token> — issued by SMS sign-in.

Top-up status after returning from the payment page. If the payment is still pending, the cloud re-requests the status from YooKassa and credits the money on success. Statuses: pending, succeeded, canceled.

Path parameters

Headers

Example request

curl -X GET "https://your-server/api/v1/wallet/payments/e4a19c7d-6b3f-4c21-8d5e-0f2a7b9c1d36" \
  -H "Authorization: Bearer <player token>"

Responses

Example response

{
  "paymentId": "e4a19c7d-6b3f-4c21-8d5e-0f2a7b9c1d36",
  "status": "succeeded",
  "amount": 5000,
  "balance": 9200
}

YooKassa notification #

Access: YooKassa only No authorization: the notification body is not trusted, the payment status is re-requested from YooKassa.

The YooKassa notification endpoint. Only object.id is taken from the body; the status and amount are re-requested from YooKassa with the shop key and checked against the cloud record. Money is credited exactly once, repeated notifications change nothing. An unknown payment — 200 with ignored=true.

Request body

Body — the YooKassa notification object; the cloud reads only object.id from it.

Example request

curl -X POST "https://your-server/api/v1/wallet/yookassa/webhook" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "notification",
  "event": "payment.succeeded",
  "object": {"id": "<YooKassa payment id>", "status": "succeeded"}
}'

Responses

Example response

{"ok": true, "status": "succeeded"}