# Quickstart Guide Welcome to the Monato Lottery API! This guide will help you get started with purchasing lottery tickets through our platform in just a few steps. ## Prerequisites Before you begin, make sure you have: - **Access Token**: A Bearer token for authentication (obtain from Monato support team) - **Payee ID**: Your unique lottery service identifier (UUID v4 format, provided by Monato) - **API Base URL**: The Monato API endpoint (contact support for the correct environment URL) ## Authentication All API requests require Bearer token authentication. Include your access token in the `Authorization` header: ```http Authorization: Bearer YOUR_ACCESS_TOKEN ``` ## Quick Start: Purchase a Lottery Ticket The lottery ticket purchase process consists of two main steps: 1. **Get current draw information** - Retrieve active draw details and pricing 2. **Purchase ticket** - Create and pay for the lottery ticket ### Step 1: Get Current Draw Information First, retrieve the current lottery draw information. This endpoint provides all the details you need to calculate the ticket price. **Request:** ```http GET /api/v1/lottery_tickets/new?payee_id=550e8400-e29b-41d4-a716-446655440000 Authorization: Bearer YOUR_ACCESS_TOKEN ``` **Response:** ```json { "draw_number": "7327", "draw_date": "13/01/2026", "base_price": 1500, "min_price": 1500, "max_price": 3780000, "rematch": 1000, "second_rematch": 500, "begin_sales": "08:00:00", "end_sales": "23:59:59", "minimum_number_of_boards": 1, "maximum_number_of_boards": 6 } ``` **Important fields:** - `draw_number`: Use this in your purchase request - `base_price`: Base price per bet in cents (1500 = $15.00 MXN) - `rematch`: Additional price for rematch option per bet in cents - `second_rematch`: Additional price for second rematch option per bet in cents - `minimum_number_of_boards` / `maximum_number_of_boards`: Limits for `combination_count` ### Step 2: Calculate Total Amount Before purchasing, calculate the total amount based on your ticket configuration: ```javascript // Price calculation formula let total = base_price * combination_count; if (rematch) { total += rematch * combination_count; } if (second_rematch && rematch) { total += second_rematch * combination_count; } // Convert to string (amounts must be strings) const total_amount = String(total); ``` **Example:** - `base_price`: 1500 cents - `combination_count`: 5 - `rematch`: true (adds 1000 per bet) - `second_rematch`: true (adds 500 per bet) ``` total = (1500 + 1000 + 500) * 5 = 15000 cents = $150.00 MXN total_amount = "15000" ``` ### Step 3: Purchase the Ticket Now create the lottery ticket purchase with the calculated amount. **Request:** ```http POST /api/v1/lottery_tickets Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json ``` **Request Body:** ```json { "payee_id": "550e8400-e29b-41d4-a716-446655440000", "payer_reference": "1234567890", "ticket": { "draw_number": "7327", "combination_count": 5, "rematch": true, "second_rematch": true, "total_amount": "15000" }, "branch": { "name": "Abarrotes Don Pepe", "city": "Ciudad de México", "street": "Av. Insurgentes Sur 1234", "neighborhood": "Del Valle" } } ``` **Response:** ```json { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "client_id": 123, "ticket": { "rematch": true, "second_rematch": true, "draw_number": "7327", "total_amount": "15000", "combination_count": 5 }, "branch": { "city": "Ciudad de Mexico", "name": "Abarrotes Don Pepe", "street": "Av. Insurgentes Sur 1234", "neighborhood": "Del Valle" }, "status": "processed", "payment": { "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321", "payer_account": "1234567890", "amount": 150.00, "currency": "MXN", "status": "completed", "pay_type": "gambling" }, "receipt": { "combination_numbers": "10,27,36,41,52,56", "transaction_date": "22/12/2025 20:19:57", "store_id": "26226", "pos_id": "1", "foreign_pos_id": "1", "transaction_number": "432930881", "reference_number": "801500019-35600002", "session_id": "80150001900", "security_number": "HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8", "serial_number": "4815-052713529-200818", "creation_date": 1769621353354 } } ``` **Important:** Store the `receipt` information, especially the `security_number`, for ticket validation and customer records. ## Code Examples ### JavaScript/Node.js ```javascript const axios = require('axios'); const API_BASE_URL = 'https://api.monato.com'; const ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'; const PAYEE_ID = '550e8400-e29b-41d4-a716-446655440000'; async function purchaseLotteryTicket() { try { // Step 1: Get current draw information const drawResponse = await axios.get( `${API_BASE_URL}/api/v1/lottery_tickets/new`, { params: { payee_id: PAYEE_ID }, headers: { Authorization: `Bearer ${ACCESS_TOKEN}` } } ); const drawInfo = drawResponse.data; console.log('Current draw:', drawInfo.draw_number); // Step 2: Calculate total amount const combinationCount = 5; const rematch = true; const secondRematch = true; let total = drawInfo.base_price * combinationCount; if (rematch) total += drawInfo.rematch * combinationCount; if (secondRematch && rematch) { total += drawInfo.second_rematch * combinationCount; } // Step 3: Purchase ticket const purchaseResponse = await axios.post( `${API_BASE_URL}/api/v1/lottery_tickets`, { payee_id: PAYEE_ID, payer_reference: `ref-${Date.now()}`, ticket: { draw_number: drawInfo.draw_number, combination_count: combinationCount, rematch: rematch, second_rematch: secondRematch, total_amount: String(total) }, branch: { name: "Abarrotes Don Pepe", city: "Ciudad de México", street: "Av. Insurgentes Sur 1234", neighborhood: "Del Valle" } }, { headers: { Authorization: `Bearer ${ACCESS_TOKEN}` } } ); console.log('Ticket purchased:', purchaseResponse.data); return purchaseResponse.data; } catch (error) { console.error('Error:', error.response?.data || error.message); throw error; } } purchaseLotteryTicket(); ``` ### Python ```python import requests import uuid API_BASE_URL = 'https://api.monato.com' ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN' PAYEE_ID = '550e8400-e29b-41d4-a716-446655440000' headers = { 'Authorization': f'Bearer {ACCESS_TOKEN}', 'Content-Type': 'application/json' } def purchase_lottery_ticket(): try: # Step 1: Get current draw information draw_response = requests.get( f'{API_BASE_URL}/api/v1/lottery_tickets/new', params={'payee_id': PAYEE_ID}, headers=headers ) draw_response.raise_for_status() draw_info = draw_response.json() print(f"Current draw: {draw_info['draw_number']}") # Step 2: Calculate total amount combination_count = 5 rematch = True second_rematch = True total = draw_info['base_price'] * combination_count if rematch: total += draw_info['rematch'] * combination_count if second_rematch and rematch: total += draw_info['second_rematch'] * combination_count # Step 3: Purchase ticket purchase_data = { 'payee_id': PAYEE_ID, 'payer_reference': str(uuid.uuid4()), 'ticket': { 'draw_number': draw_info['draw_number'], 'combination_count': combination_count, 'rematch': rematch, 'second_rematch': second_rematch, 'total_amount': str(total) }, 'branch': { 'name': 'Abarrotes Don Pepe', 'city': 'Ciudad de México', 'street': 'Av. Insurgentes Sur 1234', 'neighborhood': 'Del Valle' } } purchase_response = requests.post( f'{API_BASE_URL}/api/v1/lottery_tickets', json=purchase_data, headers=headers ) purchase_response.raise_for_status() ticket = purchase_response.json() print(f"Ticket purchased: {ticket['id']}") return ticket except requests.exceptions.RequestException as e: print(f"Error: {e.response.json() if e.response else e}") raise purchase_lottery_ticket() ``` ### cURL ```bash # Step 1: Get current draw information curl -X GET "https://api.monato.com/api/v1/lottery_tickets/new?payee_id=550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" # Step 2: Purchase ticket (replace draw_number and total_amount from Step 1) curl -X POST "https://api.monato.com/api/v1/lottery_tickets" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "payee_id": "550e8400-e29b-41d4-a716-446655440000", "payer_reference": "1234567890", "ticket": { "draw_number": "7327", "combination_count": 5, "rematch": true, "second_rematch": true, "total_amount": "15000" }, "branch": { "name": "Abarrotes Don Pepe", "city": "Ciudad de México", "street": "Av. Insurgentes Sur 1234", "neighborhood": "Del Valle" } }' ``` ## Important Notes ### Price Calculation Rules - All prices are specified in **cents** (e.g., 1500 = $15.00 MXN) - `total_amount` must be a **string** representation of the integer in cents - Always validate `combination_count` against `minimum_number_of_boards` and `maximum_number_of_boards` - Second rematch **requires** rematch to be enabled ### Validation Requirements - `payer_reference` must be unique per transaction (use UUID or timestamp-based ID) - `draw_number` must match the current active draw from Step 1 - `total_amount` must exactly match the calculated price - `combination_count` must be between the min/max limits from draw info ### Error Handling The API returns standard HTTP status codes: - `200`: Success - `401`: Authentication failed - check your Bearer token - `422`: Validation error - check request parameters and amounts ## Next Steps - Review the [API Reference](/products/lottery/lottery-openapi) for complete endpoint documentation - Explore advanced features like error handling and retry logic - Implement receipt storage for ticket validation - Contact [Monato Support](mailto:support@monato.com) for production credentials and environment details ## Support For questions or assistance: - **Email**: support@monato.com - **Documentation**: See the full API reference documentation