--- title: "Purchase a lottery ticket" method: POST path: "/api/v1/lottery_tickets" --- # Purchase a lottery ticket `POST /api/v1/lottery_tickets` ## Request - Base URL: `https://dev-api.finco.lat` - URL: `https://dev-api.finco.lat/api/v1/lottery_tickets` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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 ## Request body - CreateLotteryTicketRequest - `payee_id` string, uuid, required: Unique identifier of the lottery operator/company - `payer_reference` string, required: Payer reference (unique transaction identifier). Must be unique per transaction. Recommended to use UUID or timestamp-based ID. - `ticket` TicketRequest, required - `draw_number` string, required: Draw number obtained from GET /api/v1/lottery_tickets/new endpoint. Must match the current active draw number. - `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. - `rematch` boolean, required: Indicates if rematch option is included. If true, adds rematch price per combination from draw info. - `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. - `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 - `branch` BranchInfo, required - `name` string, required: Name of the business where the sale is being made - `street` string, required: Street address of the business - `city` string, required: City of the business - `neighborhood` string, required: Neighborhood of the business ## Response `200` Lottery ticket successfully purchased - LotteryTicketResponse - `id` string, uuid: Unique identifier of the lottery ticket - `client_id` integer: ID of the client who made the purchase - `ticket` TicketResponse - `combination_numbers` string: Selected combination numbers as comma-separated string - `draw_number` string: Identifier of the draw associated with the ticket. - `combination_count` integer: Number of combinations played - `rematch` boolean: Indicates if rematch was included - `second_rematch` boolean: Indicates if second rematch was included - `total_amount` string: Total amount paid (in cents) - `transaction_date` string: Payment date and time in DD/MM/YYYY HH:MM:SS format - `store_id` string: Identifier of the store/branch where the ticket was generated. - `pos_id` string: Point of sale ID of the integrator - `foreign_pos_id` string: Foreign point of sale identifier - `transaction_number` string: Ticket transaction number in the provider system. - `draw_date` string: Date of the associated draw - `reference_number` string: Ticket reference number - `session_id` string: Purchase session identifier - `security_number` string: Security code for anti-fraud validation. Store this value for ticket validation purposes. - `client_name` string: Name of the business where the sale was made - `client_street` string: Street address of the business - `client_city` string: City of the business - `client_neighborhood` string: Neighborhood of the business - `branch` BranchInfo - `name` string, required: Name of the business where the sale is being made - `street` string, required: Street address of the business - `city` string, required: City of the business - `neighborhood` string, required: Neighborhood of the business - `receipt` ReceiptResponse: Receipt information for ticket validation and customer records - `combination_numbers` string, required: Selected combination numbers as comma-separated string - `transaction_date` string, required: Payment date and time in DD/MM/YYYY HH:MM:SS format - `store_id` string, required: Identifier of the store/branch where the ticket was generated - `pos_id` string, required: Point of sale ID of the integrator - `foreign_pos_id` string, required: Foreign point of sale identifier - `transaction_number` string, required: Ticket transaction number in the provider system - `reference_number` string, required: Ticket reference number - `session_id` string, required: Purchase session identifier - `security_number` string, required: Security code for anti-fraud validation - `serial_number` string, required: Serial number of the ticket - `creation_date` integer, required: Unix timestamp in milliseconds when the ticket was created - `ticket_image` string, required: Image in Base64 - `status` 'pending' | 'processed' | 'completed' | 'failed': Ticket status - `payment` PaymentResponse - `id` string, uuid: Unique payment identifier - `payer_account` string: Payer reference - `payee_id` string: Service id - `amount` number: Payment amount (in monetary units, e.g., 100.00) - `currency` string: Payment currency (ISO 4217 code) - `status` 'pending' | 'completed' | 'failed': Payment status - `pay_type` string: Payment type ## Other responses - `401`: Authentication failed - `422`: Invalid input or company not found --- [API](https://skmtc.dev/monato/apis/monato-s-lottery-api.md) - [All operations](https://skmtc.dev/monato/apis/monato-s-lottery-api/llms.txt) - [OpenAPI document](https://skmtc.dev/monato/apis/monato-s-lottery-api/revisions/87f479815236?raw)