Skip to content

Distributor API Documentation

LATCOM-Compatible JSON API for Mobile Top-ups

Base URL: https://latcom-fix-production.up.railway.app/api/distributor

Authentication

All endpoints (except login) require a Bearer token in the Authorization header.

1. Login

POST /login

Get an access token using your credentials.

Request: 

{
  "customer_id": "YOUR_CUSTOMER_ID",
  "secret_key": "YOUR_SECRET_KEY"
}

Response: 

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

cURL Example: 

curl -X POST "https://latcom-fix-production.up.railway.app/api/distributor/login" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"YOUR_ID","secret_key":"YOUR_SECRET"}'

Endpoints

2. Get Balance

GET /get_balance

Check your current account balance.

Headers: - Authorization: Bearer <access_token>

Response: 

{
  "success": true,
  "balance": 1000.00,
  "currency": "USD",
  "last_updated": "2024-12-17T00:00:00.000Z"
}

cURL Example: 

curl "https://latcom-fix-production.up.railway.app/api/distributor/get_balance" \
  -H "Authorization: Bearer YOUR_TOKEN"

3. Product Purchase (Top-up)

POST /product_purchase

Execute a mobile top-up transaction.

Headers: - Authorization: Bearer <access_token> - Content-Type: application/json

Request Body: 

{
  "distributor_transaction_id": "UNIQUE_ID_FROM_YOUR_SYSTEM",
  "phone_number": "5537686660",
  "product_id": "MOVISTAR_TAE",
  "amount": 10,
  "operator": "MOVISTAR"
}

Field Type Required Description
distributor_transaction_id string Yes Your unique transaction ID for traceability
phone_number string Yes 10-digit Mexican phone number
product_id string Yes Product identifier (see Products section)
amount number Yes Amount in MXN
operator string No Carrier name (auto-detected if omitted)

Success Response: 

{
  "success": true,
  "transaction_id": "TXN-1702857600000-abc123def",
  "distributor_transaction_id": "UNIQUE_ID_FROM_YOUR_SYSTEM",
  "response_code": "00",
  "response_message": "Aprobado",
  "reference": "RRN-123456789012",
  "auth_code": "ABC123",
  "balance_after": 990.00
}

Error Response: 

{
  "success": false,
  "error": "Insufficient balance",
  "response_code": "51",
  "distributor_transaction_id": "UNIQUE_ID_FROM_YOUR_SYSTEM"
}

cURL Example: 

curl -X POST "https://latcom-fix-production.up.railway.app/api/distributor/product_purchase" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "distributor_transaction_id": "MY-TXN-001",
    "phone_number": "5537686660",
    "product_id": "MOVISTAR_TAE",
    "amount": 10,
    "operator": "MOVISTAR"
  }'

Products

Movistar TAE (Airtime)

Product ID Description Min Amount Max Amount
MOVISTAR_TAE Traditional Airtime 10 MXN 5,000 MXN

Movistar Paquetes (Data Packages)

Product ID Description Amount
MOVISTAR_PAQUETE_16 Paquete $30 30 MXN
MOVISTAR_PAQUETE_17 Paquete $50 50 MXN
MOVISTAR_PAQUETE_18 Paquete $70 70 MXN
MOVISTAR_PAQUETE_19 Paquete $90 90 MXN
MOVISTAR_PAQUETE_20 Paquete $110 110 MXN
MOVISTAR_PAQUETE_21 Paquete $150 150 MXN
MOVISTAR_PAQUETE_22 Paquete $210 210 MXN
MOVISTAR_PAQUETE_23 Paquete $320 320 MXN
MOVISTAR_PAQUETE_24 Paquete $400 400 MXN
MOVISTAR_PAQUETE_25 Paquete $420 420 MXN

Response Codes

Code Message Description
00 Aprobado Transaction approved
05 No autorizado Not authorized
12 Transaccion invalida Invalid transaction
13 Monto invalido Invalid amount
14 Paquete invalido Invalid package
51 Fondos insuficientes Insufficient funds
83 DN invalido Invalid phone number
91 Emisor no disponible Issuer not available
96 Error de sistema System error

Error Handling

All errors return a JSON response with: - success: false - error: Human-readable error message - response_code: Vendor response code (if applicable)

HTTP Status Codes

Status Description
200 Success
400 Bad Request - Missing or invalid parameters
401 Unauthorized - Invalid or missing token
402 Payment Required - Insufficient balance
500 Internal Server Error

Integration Checklist

  1. Obtain customer_id and secret_key from LATCOM
  2. Test login and token refresh
  3. Test balance inquiry
  4. Test with small amounts first
  5. Implement proper error handling
  6. Store distributor_transaction_id for reconciliation
  7. Go live!

Support

For integration support, contact your LATCOM representative.