initiatePayout(play_id)
Purpose
Initiates payout for a user’s winning play.
Automatically handles under-threshold wallet crediting or triggers KYC for high-value wins.
Endpoint
POST /api/initiate-payout/{play_id}
Authorization
- Required Scope:
user.redeem - Token: Bearer Token from user session
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| play_id | string | ✅ | Unique play ID for a winning ticket |
Response: Success – Under-Threshold Prize (200 OK)
{
"status": "credited",
"method": "wallet",
"amount": 150.00,
"transaction_id": "txn_abc123"
}
Response: Success – Over-Threshold Prize (200 OK)
{
"status": "kyc_required",
"next_step": "submit_kyc",
"claim_id": "claim_001"
}
Error States
| HTTP Code | Error Key | Description |
|---|---|---|
| 404 | play_not_found |
Play ID is invalid or unclaimed |
| 403 | not_eligible |
Play does not qualify for redemption |
| 409 | already_redeemed |
Payout was already completed |
Prize Routing Logic
- Plays ≤ $600 are credited directly to wallet or linked account
- Plays > $600 must complete KYC via
submitKYC() - Mixed-tier winnings will default to “kyc_required” if total payout exceeds threshold
Integration Notes
- Payout trigger may happen post-draw or post-results-check
- Users should be informed of required next steps if KYC applies
- Redeemed plays are marked as “locked” in downstream systems