# Welcome to Monato Lottery's API Documentation

## Description

The Monato Lottery API enables businesses and developers to integrate lottery ticket purchasing functionality into their applications. This API provides a seamless way to retrieve current lottery draw information and process ticket purchases with automatic payment handling through Monato's payment platform.

When you integrate this API, your application can:

- **Query Active Draws**: Retrieve real-time information about the current lottery draw, including pricing, sales periods, and betting limits
- **Process Ticket Purchases**: Complete the entire ticket purchase workflow, from bet configuration to payment processing
- **Handle Multiple Betting Options**: Support standard bets, rematch options, and second rematch options with automatic price calculation
- **Receive Complete Receipts**: Get detailed ticket information including security numbers, transaction details, and validation codes


The API is designed to be Developer first, providing comprehensive documentation that makes integration straightforward in any programming language. All operations are secured with Bearer token authentication, ensuring safe and reliable transactions.

## Key Features

### Real-Time Draw Information

Access up-to-date information about the current lottery draw, including draw numbers, dates, pricing structures, and sales periods. This ensures your application always works with valid, active draw data.

### Flexible Betting Options

Support multiple betting configurations:

- **Standard Bets**: Basic lottery ticket purchases with configurable number of combinations
- **Rematch Option**: Add rematch functionality to increase winning chances
- **Second Rematch**: Additional rematch layer (requires rematch to be enabled)


### Complete Payment Processing

Integrated payment handling means you don't need to manage separate payment flows. The API processes payments automatically as part of the ticket purchase transaction.

### Comprehensive Receipt Management

Receive detailed receipt information including:

- Transaction numbers and reference codes
- Security numbers for anti-fraud validation
- Store and point-of-sale identifiers
- Combination numbers and draw details
- Timestamps and creation dates


### Developer-Friendly Design

- Clear, comprehensive documentation
- Language-agnostic API design
- Standard HTTP/REST protocols
- JSON request/response format
- Detailed error messages for troubleshooting


## Operation Types

### Draw Information Retrieval

This operation allows you to query the current active lottery draw. You'll receive comprehensive information including:

- **Draw Details**: Current draw number and date
- **Pricing Structure**: Base price, rematch price, and second rematch price (all in cents)
- **Sales Period**: Start and end times for when tickets can be purchased
- **Betting Limits**: Minimum and maximum number of combinations allowed per ticket


This operation is essential before any purchase, as it provides the data needed to construct valid purchase requests.

### Ticket Purchase

This operation handles the complete ticket purchase workflow. When you execute this operation:

1. **Validation**: The system validates your request against current draw rules and limits
2. **Price Verification**: Your calculated total amount is verified against the expected price
3. **Payment Processing**: The payment is automatically processed through Monato's payment platform
4. **Ticket Generation**: A lottery ticket is created with your specified configuration
5. **Receipt Delivery**: You receive a complete receipt with all transaction details


The operation requires information about the ticket configuration (number of combinations, rematch options), branch/location details, and a unique payer reference for transaction tracking.

## Getting Started

### Prerequisites

Before you begin integrating the Lottery API, ensure you have:

1. **Access Credentials**: Obtain your Bearer token and Payee ID from the Monato support team
2. **API Endpoint**: Know the correct API base URL for your environment (sandbox or production)
3. **Integration Environment**: Set up your development environment with HTTP client capabilities


### Integration Workflow

The typical integration follows this pattern:

1. **Authenticate**: Include your Bearer token in all API requests using the Authorization header
2. **Query Draw Information**: Retrieve current draw details to get pricing and limits
3. **Submit Purchase**: Send your purchase request with the calculated amount and ticket details
4. **Handle Response**: Process the response, store receipt information, and handle any errors


### What You'll Need to Provide

- **Payee ID**: Your unique lottery service identifier (provided by Monato)
- **Payer Reference**: A unique identifier for each transaction (you generate this)
- **Ticket Configuration**: Number of combinations, rematch preferences
- **Branch Information**: Business name, address details (city, street, neighborhood)


### What You'll Receive

- **Ticket ID**: Unique identifier for the purchased ticket
- **Payment Details**: Complete payment information including status and transaction ID
- **Receipt Data**: All information needed for ticket validation and customer records
- **Security Information**: Security numbers and validation codes for fraud prevention


## Business Rules

### Draw Information Requirements

- **Always Query First**: You must retrieve current draw information before attempting any purchase
- **Use Current Data**: Draw information changes over time; always use the most recent data for purchases
- **Respect Sales Periods**: Tickets can only be purchased during the active sales period (between begin_sales and end_sales times)


### Betting Configuration Rules

- **Combination Limits**: The number of combinations per ticket must be between the minimum and maximum allowed (typically 1-6)
- **Rematch Dependencies**: Second rematch option requires rematch to be enabled
- **Price Accuracy**: The total amount you submit must exactly match the calculated price based on draw information


### Price Calculation Rules

All prices are specified in cents (e.g., 1500 cents = $15.00 MXN). The calculation follows this formula:


```
Base Total = base_price × combination_count
If rematch enabled: Add (rematch × combination_count)
If second_rematch enabled (and rematch enabled): Add (second_rematch × combination_count)
Final Amount = Base Total + Rematch Additions (as string)
```

### Transaction Rules

- **Unique References**: Each purchase must have a unique payer_reference identifier
- **Draw Number Matching**: The draw_number in your purchase must match the current active draw
- **Amount Validation**: The total_amount must be submitted as a string representation of the integer in cents


### Receipt and Security

- **Store Receipts**: Always store receipt information, especially security_number, for ticket validation
- **Customer Records**: Receipt data should be maintained for customer service and record-keeping
- **Security Numbers**: The security_number is critical for anti-fraud validation and ticket verification


### Error Handling

- **Authentication Errors**: Invalid or expired tokens will result in authentication failures
- **Validation Errors**: Incorrect amounts, invalid draw numbers, or out-of-range combination counts will be rejected
- **Business Logic Errors**: Violations of business rules (e.g., second rematch without rematch) will return validation errors


### Payment Processing

- **Automatic Processing**: Payments are processed automatically as part of the ticket purchase
- **Payment Status**: Check the payment status in the response to confirm successful processing
- **Currency**: All amounts are processed in MXN (Mexican Pesos)


## Support and Resources

For additional help and resources:

- **Quick Start Guide**: See the [Quickstart Guide](/products/lottery/guides/quickstart) for step-by-step integration examples
- **API Reference**: Review the complete [API Reference](/products/lottery/lottery-openapi) for detailed endpoint documentation
- **Support Contact**: Email support@monato.com for assistance with credentials, integration questions, or technical support