Lottery quickstart

This guide takes you from credentials to your first ticket in two calls.

Before you start

Access token. A Bearer token, from the Monato support team.
Payee ID. Your lottery service identifier, a UUID v4 provided by Monato.
Base URL. The examples use https://dev-api.finco.lat. Contact support for the URL of each environment.

Send your token on every request:

HTTP

Authorization: Bearer YOUR_ACCESS_TOKEN

1. Get the active draw

curl -X GET "https://dev-api.finco.lat/api/v1/lottery_tickets/new?payee_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "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
}

You need draw_number, the prices and the board limits for the next step. Prices are in cents: 1500 is $15.00 MXN.

2. Calculate the total

Price calculation

let total = base_price * combination_count;
if (rematch) {
  total += rematch * combination_count;
}
if (second_rematch && rematch) {
  total += second_rematch * combination_count;
}
// Amounts must be strings
const total_amount = String(total);

With 5 combinations, rematch and second rematch: (1500 + 1000 + 500) × 5 = 15000 cents, or $150.00 MXN. Send "15000".

3. Buy the ticket

curl -X POST "https://dev-api.finco.lat/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"
    }
  }'

const axios = require('axios');

const API_BASE_URL = 'https://dev-api.finco.lat';
const ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN';
const PAYEE_ID = '550e8400-e29b-41d4-a716-446655440000';

async function purchaseLotteryTicket() {
  // 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;

  // 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}` } }
  );

  return purchaseResponse.data;
}

import requests
import uuid

API_BASE_URL = 'https://dev-api.finco.lat'
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():
    # 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()

    # 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_response = requests.post(
        f'{API_BASE_URL}/api/v1/lottery_tickets',
        json={
            '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'
            }
        },
        headers=headers
    )
    purchase_response.raise_for_status()
    return purchase_response.json()

The response includes the ticket, the payment and the receipt. See Buy a ticket for the full response.

Store the receipt, especially the security_number. You need it for ticket validation and customer records.

Next steps

Show the receipt explains every receipt field.
Error codes lists the errors and what to check.
Contact support@monato.com for production credentials and environment details.