Cashout

POST /api/s2s/cashout converts a won inventory item back into wallet credit. LootBox Solutions calls your wallet.credit for the item’s cashback value, then flips the item to cashed_back.

“Cashout” here means item cashback — turning a prize the player won into balance. It is not a withdrawal of the player’s wallet to a payment method; that stays entirely on your side.

Request

POST https://{operator}.app.lootboxsolutions.com/api/s2s/cashout

{
  "playerExternalId": "u_8431",
  "inventoryItemId": 88,
  "currency": "USD",
  "idempotencyKey": "cashback:inventory:88"
}

Field	Required	Notes
`playerExternalId`	✅	Must own the item.
`inventoryItemId`	✅	The item to cash back. Must be `unresolved`.
`currency`	—	ISO 4217 of the player’s wallet. The item’s value is converted into it before the `wallet.credit`, so the credit lands in the currency your wallet holds. Omit for a single-currency player — the credit goes out in your operator currency unconverted.
`expectedRevisionId`	—	Only for collectibles: the `currentRevisionId` the player confirmed. If the item’s value has moved since, the call is refused with `PRICE_CHANGED` instead of settling at a different amount. Omit for everything else.
`idempotencyKey`	—	Defaults to `cashback:inventory:<id>`. Reuse on retry.

You own the wallet, so you name the currency the credit must arrive in. LootBox Solutions holds the item’s value in your operator currency and converts it into currency at the current rate; the wallet.credit and the response both carry that converted amount, and the operator-currency amount travels in the credit’s reference for your reconciliation.

Response — `200`

{
  "item": {
    "inventoryItemId": 88,
    "state": "cashed_back",
    "cashbackMinor": 320,
    "uncredited": { "priceFallMinor": 0, "priceRiseMinor": 0, "creditsShareMinor": 0 },
    "basisMinor": 640,
    "currency": "EUR"
  },
  "balanceAfterMinor": 11820
}

cashbackMinor is the Credits part, the amount credited to the wallet, and basisMinor the value the item was counted at (the Credits plus the fee). uncredited is the part of the item’s value the cashback did not pay in Credits, by cause, each part in currency:

Field	What was left out
`priceFallMinor`	The fall in price of a collectible counted at today’s value.
`priceRiseMinor`	The rise in price of a collectible counted at its value at win time.
`creditsShareMinor`	The cashback fee: what the item’s cashback percentage (below) did not pay in Credits.

Core pays only Credits. Whether you pay any of these parts to the player in Nuggets, or not at all, is your choice. Every cashback reports them. An item at 100% cashback that is not a collectible whose price moved reports all three as 0, and its cashbackMinor equals basisMinor.

The cashback percentage and the fee

Each item pays its own cashback in Credits, set in Catalog → Settings (a default percentage per item type) and on the item (its own percentage, a fixed amount, or none): that percentage of the value the item is counted at, rounded up to the minor unit, or the fixed amount. The rest is the fee, reported as uncredited.creditsShareMinor. An item won at 100 at 70% pays 70 in Credits and reports a fee of 30. A fixed amount above the counted value pays the fixed amount and reports no fee. An item with no cashback cannot be cashed back and reports nothing.

Collectibles whose price moved

A collectible whose price rose or fell since it was won is counted at the value the operator’s two settings pick (one for a rise, one for a fall, set in Catalog → Settings): its value at win time or today’s value (the default both ways). The price difference left out is reported in full, and the percentage applies to the counted value. For an item won at 100, now worth 80, counted at today’s value at 80%: 64 in Credits, priceFallMinor 20 and a fee (creditsShareMinor) of 16. Counted at win time instead: 80 in Credits, a fee of 20 and no fall. For an item now worth 120, counted at win time: 80 in Credits, a fee of 20 and priceRiseMinor 20; counted at today’s value: 96 in Credits and a fee of 24. The same uncredited object arrives in the wallet.credit reference: if you pay any of it in Nuggets, book them in the same transaction as the Credits, or refuse both. Converted into another currency, each part rounds up.

If your wallet refuses or is unreachable, the item is left untouched (unresolved) and the casino’s error code is returned verbatim — the player can retry.

When cashback is available

Only an unresolved item can be cashed back. Once an item is shipped, already cashed back, expired, held for or paid out in an item payout, or otherwise resolved, cashback is unavailable. An item bought with Nuggets (acquisitionType: "bought_with_nuggets") never cashes back, even inside a pending shipping order. See the inventory lifecycle.

Collectibles — confirming a value

A collectible cashes back at its current value, which can move between the moment you show the player an amount and the moment they confirm it. To make sure the player gets what they agreed to, send the value they saw:

Read the item. A collectible row carries currentRevisionId alongside cashbackMinor.
Show cashbackMinor and ask the player to confirm.
Call /cashout with expectedRevisionId set to that currentRevisionId.

If the value is still the one you quoted, the cashback settles normally. If it moved — in either direction, a rise counts too — the call is refused:

// 409
{
  "error": {
    "code": "PRICE_CHANGED",
    "message": "The item's value changed. Confirm the new amount.",
    "current": {
      "revisionId": 21980,
      "valueMinor": 9000,
      "cashbackMinor": 4500,
      "cashbackUncredited": { "priceFallMinor": 0, "priceRiseMinor": 0, "creditsShareMinor": 0 },
      "currency": "EUR"
    }
  }
}

Nothing was charged, credited or changed. The current block carries the fresh figures so you can re-prompt without a second round-trip — show the new cashbackMinor, and if the player confirms again, retry with expectedRevisionId: current.revisionId.

current is in the operator currency, not the currency you asked the credit to arrive in — it describes the item, not the payout. Convert it for display if your surface works in the player’s wallet currency, or simply re-read the inventory row with ?currency=.

Omitting expectedRevisionId keeps the previous behaviour: the cashback settles at whatever the value is when the call lands. That is fine for a normal item (its value never moves) and for an item won seconds earlier, but for a collectible sitting in a player’s vault it means the amount can differ from the one you displayed.

Errors

code	HTTP	when
`INVENTORY_ITEM_NOT_FOUND`	404	item not found or not owned by the player
`CASHBACK_NOT_AVAILABLE`	422	item not `unresolved`, bought with Nuggets, cashback disabled, no rule, or the requested `currency` has no configured rate
`PRICE_CHANGED`	409	`expectedRevisionId` is no longer the item’s current value — re-confirm; nothing was settled
`WALLET_UNAVAILABLE`	503	wallet credit failed

The game app drives the equivalent player-API cashback. This S2S endpoint is the backend-driven equivalent.