Sign in

v1

latestOpenAPI 3.1.02026-08-0621022.3 KB

Purchase a lottery ticket

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
post/api/v1/lottery_tickets

Request body

payee_idstring uuid required

Unique identifier of the lottery operator/company

payer_referencestring required

Payer reference (unique transaction identifier). Must be unique per transaction. Recommended to use UUID or timestamp-based ID.

Example request

{
  "payee_id": "550e8400-e29b-41d4-a716-446655440000",
  "payer_reference": "1234567890",
  "ticket": {
    "draw_number": "7327",
    "combination_count": 5,
    "rematch": true,
    "second_rematch": true,
    "total_amount": "10000"
  },
  "branch": {
    "name": "Abarrotes Don Pepe",
    "street": "Av. Insurgentes Sur 1234",
    "city": "Ciudad de México",
    "neighborhood": "Del Valle"
  }
}

Response

Lottery ticket successfully purchased

idstring uuid

Unique identifier of the lottery ticket

client_idinteger

ID of the client who made the purchase

status'pending' | 'processed' | 'completed' | 'failed'

Ticket status

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "client_id": 123,
  "ticket": {
    "combination_numbers": "10,27,36,41,52,56",
    "draw_number": "1234",
    "combination_count": 5,
    "rematch": true,
    "second_rematch": true,
    "total_amount": "10000",
    "transaction_date": "22/12/2025 20:19:57",
    "store_id": "26226",
    "pos_id": "1",
    "foreign_pos_id": "1",
    "transaction_number": "432930881",
    "draw_date": "DOM JUN 16 2024",
    "reference_number": "801500019-35600002",
    "session_id": "80150001900",
    "security_number": "HQTNM5-HY9YF%-QS5NZ4-Q8&Z4&-HMJ#8",
    "client_name": "Abarrotes Don Pepe",
    "client_street": "Av. Insurgentes Sur 1234",
    "client_city": "Ciudad de México",
    "client_neighborhood": "Del Valle"
  },
  "branch": {
    "name": "Abarrotes Don Pepe",
    "street": "Av. Insurgentes Sur 1234",
    "city": "Ciudad de México",
    "neighborhood": "Del Valle"
  },
  "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..."
  },
  "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"
  }
}