Purchase a lottery ticket

POST /api/v1/lottery_tickets

Try it ▸

Base URL https://dev-api.finco.lat · operationId createLotteryTicket

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:

Text

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

Authorization

BearerAuth Bearer token

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

Obtain your access token from Monato support team.

Request body application/json · required

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 object required

draw_number ticket.draw_number string required

Draw number obtained from GET /api/v1/lottery_tickets/new endpoint. Must match the current active draw number.

combination_count ticket.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 ticket.rematch boolean required

Indicates if rematch option is included. If true, adds rematch price per combination from draw info.

second_rematch ticket.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 ticket.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 object required

name branch.name string required

Name of the business where the sale is being made

street branch.street string required

Street address of the business

city branch.city string required

City of the business

neighborhood branch.neighborhood string required

Neighborhood of the business

Responses

200 Lottery ticket successfully purchased application/json

id string (uuid)

Unique identifier of the lottery ticket

client_id integer

ID of the client who made the purchase

ticket object

combination_numbers ticket.combination_numbers string

Selected combination numbers as comma-separated string

draw_number ticket.draw_number string

Identifier of the draw associated with the ticket.

combination_count ticket.combination_count integer

Number of combinations played

rematch ticket.rematch boolean

Indicates if rematch was included

second_rematch ticket.second_rematch boolean

Indicates if second rematch was included

total_amount ticket.total_amount string

Total amount paid (in cents)

transaction_date ticket.transaction_date string

Payment date and time in DD/MM/YYYY HH:MM:SS format

store_id ticket.store_id string

Identifier of the store/branch where the ticket was generated.

pos_id ticket.pos_id string

Point of sale ID of the integrator

foreign_pos_id ticket.foreign_pos_id string

Foreign point of sale identifier

transaction_number ticket.transaction_number string

Ticket transaction number in the provider system.

draw_date ticket.draw_date string

Date of the associated draw

reference_number ticket.reference_number string

Ticket reference number

session_id ticket.session_id string

Purchase session identifier

security_number ticket.security_number string

Security code for anti-fraud validation. Store this value for ticket validation purposes.

client_name ticket.client_name string

Name of the business where the sale was made

client_street ticket.client_street string

Street address of the business

client_city ticket.client_city string

City of the business

client_neighborhood ticket.client_neighborhood string

Neighborhood of the business

branch object

name branch.name string required

Name of the business where the sale is being made

street branch.street string required

Street address of the business

city branch.city string required

City of the business

neighborhood branch.neighborhood string required

Neighborhood of the business

receipt object

Receipt information for ticket validation and customer records

combination_numbers receipt.combination_numbers string required

Selected combination numbers as comma-separated string

transaction_date receipt.transaction_date string required

Payment date and time in DD/MM/YYYY HH:MM:SS format

store_id receipt.store_id string required

Identifier of the store/branch where the ticket was generated

pos_id receipt.pos_id string required

Point of sale ID of the integrator

foreign_pos_id receipt.foreign_pos_id string required

Foreign point of sale identifier

transaction_number receipt.transaction_number string required

Ticket transaction number in the provider system

reference_number receipt.reference_number string required

Ticket reference number

session_id receipt.session_id string required

Purchase session identifier

security_number receipt.security_number string required

Security code for anti-fraud validation

serial_number receipt.serial_number string required

Serial number of the ticket

creation_date receipt.creation_date integer (int64) required

Unix timestamp in milliseconds when the ticket was created

ticket_image receipt.ticket_image string required

Image in Base64

status string

Ticket status

pending processed completed failed

payment object

id payment.id string (uuid)

Unique payment identifier

payer_account payment.payer_account string

Payer reference

payee_id payment.payee_id string

Service id

amount payment.amount number (decimal)

Payment amount (in monetary units, e.g., 100.00)

currency payment.currency string

Payment currency (ISO 4217 code)

status payment.status string

Payment status

pending completed failed

pay_type payment.pay_type string

Payment type

401 Authentication failed application/json

errors array of string required

Array of error messages

422 Invalid input or company not found application/json

error string required

Error message describing the validation failure

Invalid input Company not found

This request is in the Monato · Lottery Postman collection.Download collection

Request

curl -X POST "https://dev-api.finco.lat/api/v1/lottery_tickets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "payee_id": "9432e22b-7e41-4c9e-8d59-9a73e9532342",
  "payer_reference": "1234567890",
  "ticket": {
    "draw_number": "4294",
    "combination_count": 5,
    "rematch": true,
    "second_rematch": true,
    "total_amount": "15000"
  },
  "branch": {
    "name": "Test Branch",
    "city": "Test City",
    "street": "Test Street",
    "neighborhood": "Test Neighborhood"
  }
}'

const body = JSON.stringify({
  "payee_id": "9432e22b-7e41-4c9e-8d59-9a73e9532342",
  "payer_reference": "1234567890",
  "ticket": {
    "draw_number": "4294",
    "combination_count": 5,
    "rematch": true,
    "second_rematch": true,
    "total_amount": "15000"
  },
  "branch": {
    "name": "Test Branch",
    "city": "Test City",
    "street": "Test Street",
    "neighborhood": "Test Neighborhood"
  }
});

const res = await fetch("https://dev-api.finco.lat/api/v1/lottery_tickets", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests

payload = {
  "payee_id": "9432e22b-7e41-4c9e-8d59-9a73e9532342",
  "payer_reference": "1234567890",
  "ticket": {
    "draw_number": "4294",
    "combination_count": 5,
    "rematch": True,
    "second_rematch": True,
    "total_amount": "15000"
  },
  "branch": {
    "name": "Test Branch",
    "city": "Test City",
    "street": "Test Street",
    "neighborhood": "Test Neighborhood"
  }
}

res = requests.post(
    "https://dev-api.finco.lat/api/v1/lottery_tickets",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json=payload,
)
data = res.json()

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "client_id": 123,
  "ticket": {
    "rematch": true,
    "second_rematch": true,
    "draw_number": "1234",
    "total_amount": "10000",
    "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",
    "payee_id": "9432e22b-7e41-4c9e-8d59-9a73e9532342",
    "amount": 100,
    "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,
    "ticket_image": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
  }
}

{
  "errors": [
    "Access denied"
  ]
}

{
  "error": "Invalid input"
}

{
  "error": "Company not found"
}