# Monato's Lottery API

Monato Lottery API provides endpoints for purchasing lottery tickets through Monato's payment platform.

This API is designed to be Developer/AI-first, providing comprehensive documentation for easy integration
in any programming language. All endpoints require Bearer token authentication.

**Key Features:**
- Retrieve current lottery draw information
- Purchase lottery tickets with various betting options (rematch, second rematch)
- Complete ticket purchase workflow with payment processing

**Important Notes:**
- Always call `/api/v1/lottery_tickets/new` first to get current draw information
- Prices are specified in cents (e.g., 1500 = $15.00 MXN)
- Combination count must be between minimum_number_of_boards and maximum_number_of_boards from draw info
- Second rematch requires rematch to be enabled
- Total amount must match calculated price: (base_price + rematch_price + second_rematch_price) * combination_count


Version: 1.0.0

## Servers

```
https://dev-api.finco.lat
```

## Security

### BearerAuth

Bearer token authentication. Include the token in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN

Obtain your access token from Monato support team.


Type: http
Scheme: bearer
Bearer Format: Access Token

## Download OpenAPI description

[Monato's Lottery API](https://docs.monato.com/_bundle/products/lottery/lottery-openapi.yaml)

## Other

### Retrieve current lottery draw information

 - [GET /api/v1/lottery_tickets/new](https://docs.monato.com/products/lottery/lottery-openapi/other/getlotterydraw.md): Returns the active/current lottery draw information. 

This is the first step required before purchasing a lottery ticket.

The response includes:
- Current draw number and date
- Pricing information (base price, rematch, second rematch) in cents
- Sales period (begin_sales, end_sales) in HH:MM:SS format
- Board limits (minimum_number_of_boards, maximum_number_of_boards)

Implementation Notes:
- Use the draw_number from the response in the purchase request
- Validate combination_count against minimum_number_of_boards and maximum_number_of_boards
- Use pricing information to calculate total_amount for purchase
- All prices are in cents (e.g., 1500 = $15.00 MXN)

### Purchase a lottery ticket

 - [POST /api/v1/lottery_tickets](https://docs.monato.com/products/lottery/lottery-openapi/other/createlotteryticket.md): 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