---
title: "Purchase a lottery ticket"
method: POST
path: "/api/v1/lottery_tickets"
---

# Purchase a lottery ticket

`POST /api/v1/lottery_tickets`

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.net/monato/apis/monato-s-lottery-api.md) · [All operations](https://skmtc.net/monato/apis/monato-s-lottery-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/monato/monato-s-lottery-api/revisions/87f479815236/schema)