# Purchase a lottery ticket

Creates a lottery ticket purchase for a specific draw. The system processes the bet payment.

Prerequisites:
- Must call /api/v1/lottery_tickets/new first to get current draw information
- Use draw_number from the draw info response
- Validate combination_count against draw info limits

Betting Rules:
- A ticket can have minimum 1 bet (board/combination) and maximum 6 bets
- Each bet costs the base_price from draw info (in cents, e.g., 1500 = $15.00 MXN)
- Rematch option adds rematch price per bet (in cents, e.g., 1000 = $10.00 MXN per bet)
- Second rematch option adds second_rematch price per bet (in cents, e.g., 500 = $5.00 MXN per bet)
- Second rematch requires rematch to be enabled

Price Calculation:

total = base_price * combination_count
IF rematch: total += rematch * combination_count
IF second_rematch AND rematch: total += second_rematch * combination_count
total_amount = STRING(total)  // Must be string representation of integer in cents


Implementation Notes:
- total_amount must match the calculated price based on draw info
- payer_reference must be unique per transaction (use UUID or timestamp-based ID)
- Store receipt information for ticket validation and customer records
- security_number is used for anti-fraud validation

Endpoint: POST /api/v1/lottery_tickets
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `payee_id` (string, required)
    Unique identifier of the lottery operator/company
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `payer_reference` (string, required)
    Payer reference (unique transaction identifier).
Must be unique per transaction. Recommended to use UUID or timestamp-based ID.
    Example: "1234567890"

  - `ticket` (object, required)

  - `ticket.draw_number` (string, required)
    Draw number obtained from GET /api/v1/lottery_tickets/new endpoint.
Must match the current active draw number.
    Example: "7327"

  - `ticket.combination_count` (integer, required)
    Number of combinations/boards to play.
Must be between minimum_number_of_boards and maximum_number_of_boards from draw info.
Typically 1-6, but always validate against draw info.
    Example: 5

  - `ticket.rematch` (boolean, required)
    Indicates if rematch option is included.
If true, adds rematch price per combination from draw info.
    Example: true

  - `ticket.second_rematch` (boolean, required)
    Indicates if second rematch option is included.
Requires rematch to be true. If true, adds second_rematch price per combination from draw info.
    Example: true

  - `ticket.total_amount` (string, required)
    Total amount in cents as a string representation of integer.
Must match calculated price: (base_price + rematch_price + second_rematch_price) * combination_count
Example: "10000" = $100.00 MXN
    Example: "10000"

  - `branch` (object, required)

  - `branch.name` (string, required)
    Name of the business where the sale is being made
    Example: "Abarrotes Don Pepe"

  - `branch.street` (string, required)
    Street address of the business
    Example: "Av. Insurgentes Sur 1234"

  - `branch.city` (string, required)
    City of the business
    Example: "Ciudad de México"

  - `branch.neighborhood` (string, required)
    Neighborhood of the business
    Example: "Del Valle"

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier of the lottery ticket
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `client_id` (integer)
    ID of the client who made the purchase
    Example: 123

  - `ticket` (object)

  - `ticket.combination_numbers` (string)
    Selected combination numbers as comma-separated string
    Example: "10,27,36,41,52,56"

  - `ticket.draw_number` (string)
    Identifier of the draw associated with the ticket.
    Example: "1234"

  - `ticket.combination_count` (integer)
    Number of combinations played
    Example: 5

  - `ticket.rematch` (boolean)
    Indicates if rematch was included
    Example: true

  - `ticket.second_rematch` (boolean)
    Indicates if second rematch was included
    Example: true

  - `ticket.total_amount` (string)
    Total amount paid (in cents)
    Example: "10000"

  - `ticket.transaction_date` (string)
    Payment date and time in DD/MM/YYYY HH:MM:SS format
    Example: "22/12/2025 20:19:57"

  - `ticket.store_id` (string)
    Identifier of the store/branch where the ticket was generated.
    Example: "26226"

  - `ticket.pos_id` (string)
    Point of sale ID of the integrator
    Example: "1"

  - `ticket.foreign_pos_id` (string)
    Foreign point of sale identifier
    Example: "1"

  - `ticket.transaction_number` (string)
    Ticket transaction number in the provider system.
    Example: "432930881"

  - `ticket.draw_date` (string)
    Date of the associated draw
    Example: "DOM JUN 16 2024"

  - `ticket.reference_number` (string)
    Ticket reference number
    Example: "801500019-35600002"

  - `ticket.session_id` (string)
    Purchase session identifier
    Example: "80150001900"

  - `ticket.security_number` (string)
    Security code for anti-fraud validation.
Store this value for ticket validation purposes.
    Example: "HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8"

  - `ticket.client_name` (string)
    Name of the business where the sale was made
    Example: "Abarrotes Don Pepe"

  - `ticket.client_street` (string)
    Street address of the business
    Example: "Av. Insurgentes Sur 1234"

  - `ticket.client_city` (string)
    City of the business
    Example: "Ciudad de México"

  - `ticket.client_neighborhood` (string)
    Neighborhood of the business
    Example: "Del Valle"

  - `branch` (object)

  - `receipt` (object)
    Receipt information for ticket validation and customer records

  - `receipt.combination_numbers` (string, required)
    Selected combination numbers as comma-separated string
    Example: "10,27,36,41,52,56"

  - `receipt.transaction_date` (string, required)
    Payment date and time in DD/MM/YYYY HH:MM:SS format
    Example: "22/12/2025 20:19:57"

  - `receipt.store_id` (string, required)
    Identifier of the store/branch where the ticket was generated
    Example: "26226"

  - `receipt.pos_id` (string, required)
    Point of sale ID of the integrator
    Example: "1"

  - `receipt.foreign_pos_id` (string, required)
    Foreign point of sale identifier
    Example: "1"

  - `receipt.transaction_number` (string, required)
    Ticket transaction number in the provider system
    Example: "432930881"

  - `receipt.reference_number` (string, required)
    Ticket reference number
    Example: "801500019-35600002"

  - `receipt.session_id` (string, required)
    Purchase session identifier
    Example: "80150001900"

  - `receipt.security_number` (string, required)
    Security code for anti-fraud validation
    Example: "HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8"

  - `receipt.serial_number` (string, required)
    Serial number of the ticket
    Example: "4815-052713529-200818"

  - `receipt.creation_date` (integer, required)
    Unix timestamp in milliseconds when the ticket was created
    Example: 1769621353354

  - `receipt.ticket_image` (string, required)
    Image in Base64
    Example: "iVBORw0KGgoAAAANSUhEUgAAAAUA..."

  - `status` (string)
    Ticket status
    Enum: "pending", "processed", "completed", "failed"

  - `payment` (object)

  - `payment.id` (string)
    Unique payment identifier
    Example: "f9e8d7c6-b5a4-3210-fedc-ba0987654321"

  - `payment.payer_account` (string)
    Payer reference
    Example: "1234567890"

  - `payment.payee_id` (string)
    Service id
    Example: "9432e22b-7e41-4c9e-8d59-9a73e9532342"

  - `payment.amount` (number)
    Payment amount (in monetary units, e.g., 100.00)
    Example: 100

  - `payment.currency` (string)
    Payment currency (ISO 4217 code)
    Example: "MXN"

  - `payment.status` (string)
    Payment status
    Enum: "pending", "completed", "failed"

  - `payment.pay_type` (string)
    Payment type
    Example: "gambling"

## Response 401 fields (application/json):

  - `errors` (array, required)
    Array of error messages
    Example: ["Access denied"]

## Response 422 fields (application/json):

  - `error` (string, required)
    Error message describing the validation failure
    Enum: "Invalid input", "Company not found"