Batch Deposit

`POST {api_base_url}/deposit-batch`

Credits multiple player balances in a single HTTP call. The request is an array of deposit requests (same structure as individual /deposit). The response is an array of results, each identified by tx_id.

Optional. If not implemented, Phoenix Games uses individual /deposit calls. To enable, implement this endpoint and contact Phoenix Games to set the supports_batch_deposit flag on your operator.

How It Works

Your endpoint receives an array of deposit requests and returns an array of results. Each result includes the tx_id so Phoenix Games can match it back to the original request.

Each item succeeds or fails independently
A batch can contain up to 1000 items
Items from different players, games, and instances may be mixed in one batch
You may omit items from the response - missing items will be retried

Request

The request body is a JSON array of deposit requests. Each item has the same fields as an individual /deposit request.

[
  {
    "player_id": "player_123",
    "amount": 15000,
    "game": "keno",
    "instance_id": "instance_xyz",
    "action": {
      "type": "BET",
      "round_id": "round_789",
      "wager": 10000,
      "won": 15000
    },
    "action_id": "bet_abc",
    "tx_id": "deposit:bet:bet_abc"
  },
  {
    "player_id": "player_456",
    "amount": 5000,
    "game": "keno",
    "instance_id": "instance_xyz",
    "action": {
      "type": "BET",
      "round_id": "round_789",
      "wager": 10000,
      "won": 5000
    },
    "action_id": "bet_def",
    "tx_id": "deposit:bet:bet_def"
  }
]

See Deposit for the full field reference.

Response

The response body is a JSON array of results. Each result includes the tx_id from the request plus the standard deposit response fields:

[
  {
    "tx_id": "deposit:bet:bet_abc",
    "type": "SUCCESS",
    "balance": 250.00,
    "timestamp": 1712401234567
  },
  {
    "tx_id": "deposit:bet:bet_def",
    "type": "SUCCESS",
    "balance": 120.00,
    "timestamp": 1712401234568
  }
]

Response item fields

Field	Type	Description
`tx_id`	string	The `tx_id` from the corresponding request item
`type`	string	`"SUCCESS"` or `"ERROR"`
`balance`	float	Updated player balance (required for `SUCCESS`, optional for `ERROR`)
`timestamp`	integer	Timestamp in milliseconds (required for `SUCCESS`)
`code`	string	Error code (required for `ERROR`)

What happens with each result

Result	What Phoenix Games does
`SUCCESS` for a `tx_id`	Deposit complete, player gets balance update
`ERROR` for a `tx_id`	That item will be retried
`tx_id` missing from response	That item will be retried

Idempotency is critical. If a tx_id was already processed, return SUCCESS with the current balance - not an error. This prevents unnecessary retries.

Retry Behavior

Items with ERROR responses or missing from the response will be retried with exponential backoff
Successfully processed items are never resent
If the HTTP request itself fails (timeout, connection error), all items in that batch are retried

Timeouts

Batch requests have a 120-second timeout (vs 30s for individual deposits). Your endpoint should be able to process up to 1000 deposits within this window.

Security

Batch requests are signed identically to individual requests:

The entire JSON array body is signed with RSA SHA256
Signature is included in the signature header
Verify the signature covers the full request body

Important

Each response item must include the tx_id from the corresponding request
If a tx_id was already processed, return SUCCESS with the current balance - not an error

Testing Checklist

Basic batch - Send 3-5 deposits, verify all balances update correctly
Idempotency - Send the same batch twice, verify balances only credited once and both responses return SUCCESS
Mixed results - Include one invalid player in a batch of valid ones, verify valid items succeed and invalid one returns ERROR
Single player, multiple bets - All items for one player, verify final balance is correct
Large batch - Send 1000 items, verify all processed within 120s
tx_id matching - Verify each response item includes the correct tx_id

On this page