Cancel

POST /api/s2s/cancel reverses a pre-pay purchase: it refunds a box the player bought but has not opened, calling your wallet.credit for the original amount and moving the round to refunded.

When to use it

Cancel applies to exactly one situation: a held (pre-paid, unopened) box.

✅ Use it when:

• A player bought a box (e.g. via a “Buy now” widget) and changes their mind before opening it.
• Your support/operations needs to reverse a mistaken pre-pay purchase.
• A held box hits an expiry or policy condition you want to unwind.

❌ It does not apply to:

• Atomic opens — a buy-&-open round is settled the instant it’s made; its outcome is realized and there is nothing to cancel.
• Already-opened boxes — once a held box is opened it becomes settled and is terminal. You cannot reverse an open or claw back a result.
• Won prizes — to convert a prize to balance use cashout, not cancel.

In short: cancel = “return the unopened box”, never “undo a play.”

Policy

Refundability is governed by a per-operator / per-box policy (alongside cashback and shipping policies). If a held box isn’t refundable under your policy, cancel returns REFUND_NOT_ALLOWED. Configure it in operator settings.

Request

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

{
  "playerExternalId": "u_8431",
  "roundPublicId": "r_01J…",
  "idempotencyKey": "refund:round:r_01J…"
}

Field	Required	Notes
playerExternalId	✅	Must own the held round.
roundPublicId	✅	The held round to refund.
idempotencyKey	—	Defaults to refund:round:<publicId>. Reuse on retry.

Response — 200

{
  "round": { "publicId": "r_01J…", "status": "refunded", "refundedMinor": 500, "currency": "EUR" },
  "balanceAfterMinor": 12000
}

The round moves to refunded — distinct from voided (a debit that was refused and never moved money). See round lifecycle.

Errors

code	HTTP	when
ROUND_NOT_FOUND	404	round not found or not owned by the player
ROUND_NOT_REFUNDABLE	409	round is not held (already opened, atomic, or already refunded)
REFUND_NOT_ALLOWED	403	operator/box policy forbids refunds
WALLET_UNAVAILABLE	503	wallet credit failed — round stays held, retry later