Skip to content
Star GameStar Game Docs

Apply a batch of 1–500 debits, credits and rollbacks

POST
/transactions
curl --request POST \
  --url https://operator.example.com/game-wallet/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'webhook-signature: <webhook-signature>' \
  --data '{ "transactions": [ { "transaction_id": "lantern:59666:9100001234567890123:bet", "type": "debit", "player_id": "example", "session_id": "example", "amount": "1500", "currency": "example", "game_id": "example", "round_id": "example", "room_id": "example", "reference_transaction_id": "example", "created_at": "2026-04-15T12:00:00Z", "details": {} } ] }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
transactions
required
Array<object>
>= 1 items <= 500 items
object
transaction_id
required
string
<= 128 characters

Example 

lantern:59666:9100001234567890123:bet
type
required
string
Allowed values: debit credit rollback
player_id
required
string
session_id

Debit only

string
amount

Integer amount in minor units, as a decimal string.

string
/^-?[0-9]{1,19}$/

Example 

1500
currency

Debit and credit

string
game_id
required
string
round_id

Groups all transactions of one game round

string
room_id

Operator room the player played from, if any

string
reference_transaction_id

Rollback: the debit to reverse (required). credit: the debit it pays out (optional).

string
created_at
string format: date-time
details

Opaque, human-readable breakdown for operator support tools (e.g. which options were bet).

object
key
additional properties
any

Responses

Section titled “Responses”

200

Section titled “200”

One result per transaction, in request order

Media typeapplication/json
object
results
required
Array<object>
object
transaction_id
required
string
status
required
  • ok — booked now or earlier (also for rollbacks with nothing to reverse)
  • insufficient_funds — debit not booked; include balance
  • session_invalid / player_blocked / limit_exceeded — debit not booked
  • duplicate_mismatch — same id, different content; nothing booked
  • reference_not_found — credit whose referenced debit was never booked or was rolled back
  • rolled_back — debit arriving after its rollback; not booked
  • retry — transient failure, nothing booked; the platform resends the same transaction
string
Allowed values: ok insufficient_funds session_invalid player_blocked limit_exceeded duplicate_mismatch reference_not_found rolled_back retry
balance

Integer amount in minor units, as a decimal string.

string
/^-?[0-9]{1,19}$/
processed_at
string format: date-time

Example 

{
  "results": [
    {
      "status": "ok",
      "balance": "1500"
    }
  ]
}

400

Section titled “400”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
Allowed values: invalid_signature invalid_launch_code malformed_request player_not_found transaction_not_found rate_limited unavailable internal not_found
detail
string

Example 

{
  "type": "https://game-platform.dev/problems/rate_limited",
  "code": "invalid_signature"
}

401

Section titled “401”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
Allowed values: invalid_signature invalid_launch_code malformed_request player_not_found transaction_not_found rate_limited unavailable internal not_found
detail
string

Example 

{
  "type": "https://game-platform.dev/problems/rate_limited",
  "code": "invalid_signature"
}

429

Section titled “429”

rate_limited; retry after Retry-After seconds with the same transactions

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
Allowed values: invalid_signature invalid_launch_code malformed_request player_not_found transaction_not_found rate_limited unavailable internal not_found
detail
string

Example 

{
  "type": "https://game-platform.dev/problems/rate_limited",
  "code": "invalid_signature"
}

Headers

Section titled “Headers”
Retry-After
integer
>= 1

Seconds to wait before retrying

503

Section titled “503”

unavailable; outcome unknown for the whole batch, retry with the same transactions

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
Allowed values: invalid_signature invalid_launch_code malformed_request player_not_found transaction_not_found rate_limited unavailable internal not_found
detail
string

Example 

{
  "type": "https://game-platform.dev/problems/rate_limited",
  "code": "invalid_signature"
}

Headers

Section titled “Headers”
Retry-After
integer
>= 1

Seconds to wait before retrying

default

Section titled “default”

RFC 9457 problem details

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
Allowed values: invalid_signature invalid_launch_code malformed_request player_not_found transaction_not_found rate_limited unavailable internal not_found
detail
string

Example 

{
  "type": "https://game-platform.dev/problems/rate_limited",
  "code": "invalid_signature"
}