Buy a ticket | Lottery

One request validates the ticket, verifies the price, processes the payment, creates the ticket and returns the receipt.

Before you start

Get the active draw. You need its draw_number, prices and board limits.

Calculate the total

Prices are in cents. Multiply each price by the number of combinations:

Price formula

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)

Example: base_price 1500, rematch 1000, second_rematch 500 and 5 combinations give (1500 + 1000 + 500) × 5 = 15000. Send "15000" ($150.00 MXN).

Request

Buy a 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"
    }
  }'

Field	Required	Description
`payee_id`	Yes	Your lottery service identifier
`payer_reference`	Yes	Unique per transaction. Use a UUID or a timestamp-based ID.
`ticket.draw_number`	Yes	Must match the current active draw
`ticket.combination_count`	Yes	Between the draw’s minimum and maximum number of boards
`ticket.rematch`	Yes	Include the rematch option
`ticket.second_rematch`	Yes	Include the second rematch option. Requires `rematch: true`.
`ticket.total_amount`	Yes	Total in cents as a string of digits. Must match the calculated price.
`branch.name`	Yes	Name of the business where the sale is made
`branch.street`	Yes	Street address of the business
`branch.city`	Yes	City of the business
`branch.neighborhood`	Yes	Neighborhood of the business

See Purchase a lottery ticket.

Response

200 OK

{
  "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",
    "payee_id": "550e8400-e29b-41d4-a716-446655440000",
    "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,
    "ticket_image": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
  }
}

status is the ticket status: pending, processed, completed or failed.
payment.status is pending, completed or failed. Check it to confirm the payment succeeded.
payment.amount is in monetary units (150.00), while ticket.total_amount is in cents.

Store the receipt, especially the security_number. See Show the receipt.

Validation rules

Your request is rejected if:

total_amount does not match the calculated price.
draw_number is not the current active draw.
combination_count is outside the draw’s limits.
second_rematch is true while rematch is false.

See Error codes.