Multipliers

The Banca Management Backend uses a flexible multiplier system that determines payout amounts for winning bets. Multipliers can be configured at multiple levels with hierarchical resolution.

What are Multipliers?

A multiplier (represented as multiplierX or finalMultiplierX) is a numeric value that determines the payout for a winning bet:

Payout = Bet Amount × Multiplier

Example:

Bet Amount: 100 colones
Multiplier: 80
Payout if win: 100 × 80 = 8,000 colones

Multiplier Types

Base Multiplier

Applied to standard NUMERO bets. Resolved hierarchically with 5-level priority.

REVENTADO Multiplier

Applied when a REVENTADO bet wins. Configured per sorteo when evaluating results.

Base Multiplier Resolution

When a NUMERO bet is placed, the base multiplier is resolved using a 5-level priority chain (first match wins):

1. User Multiplier Override

Individual user-specific override for a specific loteria.

SELECT baseMultiplierX FROM UserMultiplierOverride
WHERE userId = ? AND loteriaId = ? AND isActive = true

2. Banca Loteria Setting

Banca-level setting for a specific loteria.

SELECT baseMultiplierX FROM BancaLoteriaSetting
WHERE bancaId = ? AND loteriaId = ?

3. Loteria Multiplier

Loteria-level multiplier with name="Base" or first active kind="NUMERO".

SELECT multiplierX FROM LoteriaMultiplier
WHERE loteriaId = ? AND isActive = true AND name = 'Base'
ORDER BY createdAt ASC LIMIT 1

4. Loteria Rules JSON

Fallback value in loteria’s rulesJson.baseMultiplierX.

loteria.rulesJson?.baseMultiplierX

5. System Default

Global environment variable fallback.

MULTIPLIER_BASE_DEFAULT_X=95

The resolved multiplier is frozen as finalMultiplierX in the jugada at ticket creation time, ensuring payout consistency even if multipliers change later.

Loteria Multipliers

Loteria multipliers are configured per lottery and can have different types:

Creating a Loteria Multiplier

curl -X POST http://localhost:4000/api/v1/multipliers \
  -H "Authorization: Bearer {adminToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "loteriaId": "loteria-uuid",
    "name": "Base",
    "kind": "NUMERO",
    "multiplierX": 80,
    "isActive": true
  }'

Creating a REVENTADO Multiplier

curl -X POST http://localhost:4000/api/v1/multipliers \
  -H "Authorization: Bearer {adminToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "loteriaId": "loteria-uuid",
    "name": "REVENTADO Especial",
    "kind": "REVENTADO",
    "multiplierX": 500,
    "isActive": true,
    "appliesToSorteoId": "specific-sorteo-uuid"
  }'

name

string

required

Display name for the multiplier (e.g., “Base”, “REVENTADO Especial”)

kind

enum

required

Type of multiplier: NUMERO or REVENTADO

multiplierX

number

required

Multiplier value (e.g., 80, 500)

isActive

boolean

Whether the multiplier is active (default: true)

appliesToSorteoId

string

Optional: Restrict to a specific sorteo (used for REVENTADO)

User Multiplier Overrides

Admins can set custom multipliers for specific users and loterias:

curl -X POST http://localhost:4000/api/v1/multiplier-overrides \
  -H "Authorization: Bearer {adminToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "vendedor-uuid",
    "loteriaId": "loteria-uuid",
    "baseMultiplierX": 85,
    "isActive": true
  }'

User overrides take highest priority in the resolution chain, allowing you to give specific vendedores better multipliers as incentives.

REVENTADO Multipliers

REVENTADO is a special bet type that can win an extra multiplier if the winning number matches the bet number. The REVENTADO multiplier is applied when evaluating a sorteo:

Evaluating a Sorteo with REVENTADO

curl -X PATCH http://localhost:4000/api/v1/sorteos/{sorteoId}/evaluate \
  -H "Authorization: Bearer {adminToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "winningNumber": "42",
    "extraMultiplierId": "reventado-multiplier-uuid",
    "extraOutcomeCode": "ROJA"
  }'

What happens:

All NUMERO bets on number “42” are marked as winners
All REVENTADO bets on number “42” with matching color receive the extra multiplier
The extraMultiplierX value is snapshot to the sorteo and jugadas
Payouts are calculated:
- NUMERO: amount × baseMultiplierX
- REVENTADO (winning): amount × reventadoMultiplierX

REVENTADO Validation

When evaluating with REVENTADO:

extraMultiplierId must be a valid, active multiplier with kind="REVENTADO"
If appliesToSorteoId is set on the multiplier, it must match the sorteo being evaluated
The multiplier must belong to the same loteria

Multiplier Snapshot Immutability

Multipliers are captured as immutable snapshots at critical moments:

At Ticket Creation (NUMERO)

{
  "jugadaId": "uuid",
  "number": "42",
  "amount": 100,
  "betType": "NUMERO",
  "multiplierId": "base-multiplier-uuid",
  "finalMultiplierX": 80,  // ← Frozen at creation
  "potentialPayout": 8000   // ← 100 × 80
}

At Sorteo Evaluation (REVENTADO)

{
  "sorteoId": "uuid",
  "winningNumber": "42",
  "extraMultiplierId": "reventado-multiplier-uuid",
  "extraMultiplierX": 500,  // ← Frozen at evaluation
  "status": "EVALUATED"
}

REVENTADO jugadas also get the snapshot:

{
  "jugadaId": "uuid",
  "number": "42",
  "amount": 100,
  "betType": "REVENTADO",
  "color": "ROJA",
  "finalMultiplierX": 500,  // ← Updated from sorteo's extraMultiplierX
  "payout": 50000,          // ← 100 × 500 (if won)
  "isWinner": true
}

Listing Multipliers

# List all multipliers for a loteria
curl "http://localhost:4000/api/v1/multipliers?loteriaId=uuid&isActive=true" \
  -H "Authorization: Bearer {accessToken}"

# Filter by kind
curl "http://localhost:4000/api/v1/multipliers?kind=REVENTADO" \
  -H "Authorization: Bearer {accessToken}"

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid-1",
      "loteriaId": "loteria-uuid",
      "name": "Base",
      "kind": "NUMERO",
      "multiplierX": 80,
      "isActive": true,
      "createdAt": "2025-01-01T00:00:00.000Z"
    },
    {
      "id": "uuid-2",
      "loteriaId": "loteria-uuid",
      "name": "REVENTADO Alto",
      "kind": "REVENTADO",
      "multiplierX": 500,
      "isActive": true,
      "appliesToSorteoId": "sorteo-uuid",
      "createdAt": "2025-02-15T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

Updating Multipliers

Only ADMIN users can update multipliers:

curl -X PATCH http://localhost:4000/api/v1/multipliers/{multiplierId} \
  -H "Authorization: Bearer {adminToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "multiplierX": 85,
    "isActive": true
  }'

Updating a multiplier does not affect existing tickets. Only new tickets created after the update will use the new value.

Configuration in Loteria Rules

You can set a default multiplier in the loteria’s rulesJson:

{
  "name": "Lotto",
  "rulesJson": {
    "baseMultiplierX": 80,
    "allowedBetTypes": ["NUMERO", "REVENTADO"],
    "reventadoConfig": {
      "enabled": true,
      "requiresMatchingNumber": true,
      "colors": ["ROJA", "VERDE"]
    }
  }
}

This serves as a fallback if no LoteriaMultiplier with name="Base" exists.

Environment Configuration

Set a system-wide default multiplier:

# .env
MULTIPLIER_BASE_DEFAULT_X=95

This is used as the last resort if no other multiplier source is found.

Best Practices

Always create a Base multiplier for each loteria

Ensure every loteria has at least one LoteriaMultiplier with name="Base" and kind="NUMERO" to avoid falling back to environment defaults.

Use user overrides sparingly

User multiplier overrides are powerful but can create inconsistencies. Use them for:

Promotional incentives
VIP vendedores
Testing new multiplier values

Document all overrides and review them regularly.

Set REVENTADO multipliers per sorteo

For special draws, create REVENTADO multipliers with appliesToSorteoId to ensure they only apply to specific sorteos:

# REVENTADO for specific sorteo
{
  "name": "REVENTADO Especial - Sorteo 12:55",
  "kind": "REVENTADO",
  "multiplierX": 600,
  "appliesToSorteoId": "sorteo-1255-uuid"
}

Monitor payout exposure

Higher multipliers increase payout exposure. Use the exposure analytics endpoint to monitor risk:

curl "http://localhost:4000/api/v1/admin/dashboard/exposure?sorteoId=uuid" \
  -H "Authorization: Bearer {adminToken}"

Sorteo Evaluation

How to evaluate sorteos with REVENTADO

Ticket Creation

How multipliers are applied to tickets

Exposure Analytics

Monitor payout risk by multiplier

Get Started

Core Concepts

Guides

Operations

What are Multipliers?

Multiplier Types

Base Multiplier

REVENTADO Multiplier

Base Multiplier Resolution

Loteria Multipliers

Creating a Loteria Multiplier

Creating a REVENTADO Multiplier

User Multiplier Overrides

REVENTADO Multipliers

Evaluating a Sorteo with REVENTADO

REVENTADO Validation

Multiplier Snapshot Immutability

At Ticket Creation (NUMERO)

At Sorteo Evaluation (REVENTADO)

Listing Multipliers

Updating Multipliers

Configuration in Loteria Rules

Environment Configuration

Best Practices

Sorteo Evaluation

Ticket Creation

Exposure Analytics

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Operations

​What are Multipliers?

​Multiplier Types

Base Multiplier

REVENTADO Multiplier

​Base Multiplier Resolution

​Loteria Multipliers

​Creating a Loteria Multiplier

​Creating a REVENTADO Multiplier

​User Multiplier Overrides

​REVENTADO Multipliers

​Evaluating a Sorteo with REVENTADO

​REVENTADO Validation

​Multiplier Snapshot Immutability

​At Ticket Creation (NUMERO)

​At Sorteo Evaluation (REVENTADO)

​Listing Multipliers

​Updating Multipliers

​Configuration in Loteria Rules

​Environment Configuration

​Best Practices

​Related Resources

Sorteo Evaluation

Ticket Creation

Exposure Analytics

Build docs developers (and LLMs) love

What are Multipliers?

Multiplier Types

Base Multiplier Resolution

Loteria Multipliers

Creating a Loteria Multiplier

Creating a REVENTADO Multiplier

User Multiplier Overrides

REVENTADO Multipliers

Evaluating a Sorteo with REVENTADO

REVENTADO Validation

Multiplier Snapshot Immutability

At Ticket Creation (NUMERO)

At Sorteo Evaluation (REVENTADO)

Listing Multipliers

Updating Multipliers

Configuration in Loteria Rules

Environment Configuration

Best Practices

Related Resources