`fulfillHighValuePlay(play_id)`

Purpose

Triggers the physical fulfillment flow for high-value lottery plays (>$600).
Initiates courier dispatch, logs custody chain, and provides claim ETA tracking.

Endpoint

POST /api/fulfill-high-value/{play_id}

Authorization

Required Scope: claim.fulfill or ops.dispatch
Token: Bearer Token required

Parameters

Name	Type	Required	Description
play_id	string	✅	UUID of the user’s winning play

Response: Success (200 OK)

{
  "ticket_id": "abc123",
  "courier_id": "c9f887d3",
  "envelope_id": "env-22a94",
  "pickup_scheduled": "2025-06-25T14:00:00Z",
  "pickup_confirmed": false,
  "delivered_to": "drawn_claim_center",
  "delivery_eta": "2025-06-26T12:00:00Z"
}

Error States

HTTP Code	Error Key	Description
404	`play_not_found`	The play ID does not exist in the system
400	`not_high_value_win`	Play is not eligible for physical claim
409	`already_fulfilled`	Fulfillment has already been dispatched

Webhooks Triggered

high_value_fulfillment_started
Optional: status updates on pickup & delivery via courier app

Integration Notes

Call only if initiatePayout() returns a kyc_required status with prize > $600.
Store envelope_id for downstream scan and custody workflows.
Use verifyCourierScan() to confirm pickup.
Use confirmEnvelopeDelivery() to complete custody chain.