Skip to content

Via.One API Documentation v1.0

Official API Documentation for Via.One Payment Services Platform

Table of Contents

  1. Introduction
  2. Authentication
  3. Environments
  4. Services Overview
  5. Airtime Topups
  6. Bill Payments
  7. Bank Transfers (SPEI)
  8. Cash Payment Methods
  9. Response Codes
  10. Error Handling
  11. Support

Introduction

Via.One provides a comprehensive payment services platform for Mexico, offering:

  • Mobile Airtime Topups - Telefonica Movistar, Telcel, AT&T, Unefon, Virgin Mobile
  • Bill Payments - Electricity, water, gas, telecom, and 100+ service providers
  • Bank Transfers (SPEI) - Real-time electronic transfers
  • Cash Payments - OXXO and Enefevo barcode generation

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

API Version: 1.0 Protocol: HTTPS only Data Format: JSON Character Encoding: UTF-8

Authentication

Via.One uses API Key authentication with customer-specific credentials.

Authentication Header

Include your credentials in every API request:

Authorization: Bearer YOUR_API_KEY
X-Customer-ID: YOUR_CUSTOMER_ID
Content-Type: application/json

Obtaining Credentials

Contact Via.One to receive your production credentials:

  • Email: support@relier.group
  • Phone: +1 (704) 649-0570

You will receive: - API_KEY - Your unique API authentication key - CUSTOMER_ID - Your customer identifier - WEBHOOK_SECRET - Secret for webhook signature verification (optional)

Test Credentials

Test Environment: 

API_KEY: test_viaone_key_cellpay_sandbox
CUSTOMER_ID: cellpay_test_001

Environments

Production Environment

Base URL: https://latcom-fix-production.up.railway.app
  • Real transactions with actual carriers and service providers
  • Charges will be applied to your account balance
  • Use production credentials only

Test Environment

Base URL: https://latcom-fix-production.up.railway.app
  • Simulated transactions (use test credentials)
  • No real charges applied
  • Use for integration testing and development

Note: Test transactions use the same base URL but are identified by test credentials.

Services Overview

Service Endpoint Methods Currency
Airtime Topups /api/v1/topup POST MXN
Bill Payments /api/v1/bill-payment POST MXN
SPEI Transfers /api/v1/spei POST MXN
OXXO Payments /api/v1/oxxo POST MXN
Enefevo Payments /api/v1/enefevo POST MXN
Transaction Status /api/v1/transaction/:id GET -
Balance Inquiry /api/v1/balance GET MXN

Airtime Topups

Process mobile airtime recharges for Mexican carriers.

Supported Carriers

Carrier Code Min Amount Max Amount
Telefonica Movistar MOVISTAR 10 MXN 500 MXN
Telcel TELCEL 10 MXN 500 MXN
AT&T ATT 10 MXN 500 MXN
Unefon UNEFON 20 MXN 500 MXN
Virgin Mobile VIRGIN 20 MXN 500 MXN

Request: Process Topup

Endpoint: POST /api/v1/topup

Request Body:

{
  "carrier": "MOVISTAR",
  "phone": "5512345678",
  "amount": 50,
  "reference": "ORDER-12345"
}

Parameters:

Parameter Type Required Description
carrier string Yes Carrier code (MOVISTAR, TELCEL, ATT, etc.)
phone string Yes 10-digit Mexican phone number (without country code)
amount number Yes Amount in MXN (must match available denominations)
reference string Yes Your unique transaction reference (max 50 chars)

Available Denominations: 10, 20, 30, 50, 80, 100, 150, 200, 300, 500 MXN

Response (Success):

{
  "success": true,
  "transaction_id": "VIA-20251108-001234",
  "carrier": "MOVISTAR",
  "phone": "5512345678",
  "amount": 50,
  "currency": "MXN",
  "status": "completed",
  "authorization_code": "AUTH-789456",
  "timestamp": "2025-11-08T15:30:00Z",
  "reference": "ORDER-12345"
}

Response (Error):

{
  "success": false,
  "error_code": "INVALID_AMOUNT",
  "error_message": "Amount must be one of: 10, 20, 30, 50, 80, 100, 150, 200, 300, 500",
  "transaction_id": "VIA-20251108-001234",
  "timestamp": "2025-11-08T15:30:00Z"
}

Example: cURL

curl -X POST https://latcom-fix-production.up.railway.app/api/v1/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Customer-ID: YOUR_CUSTOMER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "carrier": "MOVISTAR",
    "phone": "5512345678",
    "amount": 50,
    "reference": "ORDER-12345"
  }'

Example: Node.js

const axios = require('axios');

const topup = async () => {
  try {
    const response = await axios.post(
      'https://latcom-fix-production.up.railway.app/api/v1/topup',
      {
        carrier: 'MOVISTAR',
        phone: '5512345678',
        amount: 50,
        reference: 'ORDER-12345'
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'X-Customer-ID': 'YOUR_CUSTOMER_ID',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Topup successful:', response.data);
  } catch (error) {
    console.error('Topup failed:', error.response.data);
  }
};

topup();

Example: Python

import requests

url = 'https://latcom-fix-production.up.railway.app/api/v1/topup'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Customer-ID': 'YOUR_CUSTOMER_ID',
    'Content-Type': 'application/json'
}
data = {
    'carrier': 'MOVISTAR',
    'phone': '5512345678',
    'amount': 50,
    'reference': 'ORDER-12345'
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Bill Payments

Pay utility bills and services for Mexican service providers.

Supported Services

  • Electricity: CFE (Comisión Federal de Electricidad)
  • Water: Multiple municipal water services
  • Gas: Natural gas and LP gas providers
  • Telecommunications: Internet, cable TV, phone
  • And 100+ additional service providers

Request: Process Bill Payment

Endpoint: POST /api/v1/bill-payment

Request Body:

{
  "company_code": "CFE-CFE",
  "reference_number": "977191002290",
  "amount": 850.50,
  "customer_reference": "BILL-67890"
}

Parameters:

Parameter Type Required Description
company_code string Yes Service provider code (see supported companies)
reference_number string Yes Customer account/service number
amount number Yes Amount to pay in MXN
customer_reference string Yes Your unique transaction reference

Response (Success):

{
  "success": true,
  "transaction_id": "VIA-20251108-001235",
  "company": "CFE - Comisión Federal de Electricidad",
  "company_code": "CFE-CFE",
  "reference_number": "977191002290",
  "amount": 850.50,
  "currency": "MXN",
  "status": "completed",
  "authorization_code": "AUTH-456789",
  "timestamp": "2025-11-08T15:35:00Z",
  "customer_reference": "BILL-67890"
}

Get Supported Companies

Endpoint: GET /api/v1/bill-payment/companies

Response:

{
  "success": true,
  "companies": [
    {
      "code": "CFE-CFE",
      "name": "CFE - Comisión Federal de Electricidad",
      "category": "electricity",
      "min_amount": 1,
      "max_amount": 50000
    },
    {
      "code": "TELMEX",
      "name": "Telmex",
      "category": "telecommunications",
      "min_amount": 1,
      "max_amount": 10000
    }
  ]
}

Bank Transfers (SPEI)

Process instant bank transfers using Mexico's SPEI (Sistema de Pagos Electrónicos Interbancarios) network.

Request: Create SPEI Transfer

Endpoint: POST /api/v1/spei

Request Body:

{
  "amount": 5000.00,
  "recipient_name": "Juan Pérez García",
  "recipient_bank": "012",
  "recipient_account": "012180001234567890",
  "recipient_clabe": "012180001234567890",
  "reference": "Payment for services",
  "customer_reference": "SPEI-123456"
}

Parameters:

Parameter Type Required Description
amount number Yes Amount in MXN (min: 1, max: 1,000,000)
recipient_name string Yes Full name of recipient
recipient_bank string Yes Bank code (3 digits)
recipient_account string Yes Bank account number
recipient_clabe string Yes 18-digit CLABE account number
reference string Yes Payment description (max 40 chars)
customer_reference string Yes Your unique transaction reference

Response (Success):

{
  "success": true,
  "transaction_id": "VIA-20251108-001236",
  "spei_tracking": "2025110812345678901234",
  "amount": 5000.00,
  "currency": "MXN",
  "recipient_name": "Juan Pérez García",
  "recipient_clabe": "012180001234567890",
  "status": "completed",
  "timestamp": "2025-11-08T15:40:00Z",
  "customer_reference": "SPEI-123456"
}

Processing Time: Instant (typically under 30 seconds)

Operating Hours: 24/7 including weekends and holidays

Cash Payment Methods

Generate payment barcodes for customers to pay with cash at convenience stores.

OXXO Payments

Generate OXXO payment barcodes for cash collection.

Endpoint: POST /api/v1/oxxo

Request Body:

{
  "amount": 250.00,
  "customer_name": "María González",
  "customer_email": "maria@example.com",
  "description": "Product purchase",
  "expiry_days": 3,
  "customer_reference": "OXXO-789012"
}

Parameters:

Parameter Type Required Description
amount number Yes Amount in MXN (min: 10, max: 10,000)
customer_name string Yes Customer full name
customer_email string No Email for receipt (optional)
description string Yes Payment description
expiry_days number No Days until expiry (default: 3, max: 7)
customer_reference string Yes Your unique transaction reference

Response:

{
  "success": true,
  "transaction_id": "VIA-20251108-001237",
  "payment_method": "OXXO",
  "amount": 250.00,
  "currency": "MXN",
  "status": "pending",
  "barcode": "9876543210987654321098",
  "barcode_url": "https://via.one/barcode/9876543210987654321098.png",
  "payment_url": "https://via.one/pay/VIA-20251108-001237",
  "instructions": "Present this barcode at any OXXO store to complete payment",
  "expires_at": "2025-11-11T23:59:59Z",
  "timestamp": "2025-11-08T15:45:00Z",
  "customer_reference": "OXXO-789012"
}

Webhook Notification: You will receive a webhook when payment is completed at OXXO.

Enefevo Payments

Generate Enefevo payment barcodes for cash collection.

Endpoint: POST /api/v1/enefevo

Request Body:

{
  "amount": 150.00,
  "customer_name": "Carlos Ramírez",
  "description": "Service payment",
  "customer_reference": "ENEFEVO-345678"
}

Response: Similar structure to OXXO payments with Enefevo-specific barcode.

Transaction Status

Check the status of any transaction.

Endpoint: GET /api/v1/transaction/:transaction_id

Example:

curl -X GET https://latcom-fix-production.up.railway.app/api/v1/transaction/VIA-20251108-001234 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Customer-ID: YOUR_CUSTOMER_ID"

Response:

{
  "success": true,
  "transaction_id": "VIA-20251108-001234",
  "type": "topup",
  "status": "completed",
  "amount": 50,
  "currency": "MXN",
  "carrier": "MOVISTAR",
  "phone": "5512345678",
  "authorization_code": "AUTH-789456",
  "created_at": "2025-11-08T15:30:00Z",
  "completed_at": "2025-11-08T15:30:05Z",
  "reference": "ORDER-12345"
}

Transaction Statuses:

  • pending - Transaction initiated, awaiting processing
  • processing - Transaction in progress
  • completed - Transaction successful
  • failed - Transaction failed
  • cancelled - Transaction cancelled
  • refunded - Transaction refunded

Balance Inquiry

Check your current account balance.

Endpoint: GET /api/v1/balance

Example:

curl -X GET https://latcom-fix-production.up.railway.app/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Customer-ID: YOUR_CUSTOMER_ID"

Response:

{
  "success": true,
  "customer_id": "cellpay_prod_001",
  "balance": 125000.50,
  "currency": "MXN",
  "available_balance": 125000.50,
  "pending_balance": 0.00,
  "last_updated": "2025-11-08T15:50:00Z"
}

Response Codes

HTTP Status Codes

Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing authentication
403 Forbidden Insufficient permissions or balance
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error
503 Service Unavailable Service temporarily unavailable

Via.One Error Codes

Error Code Description Resolution
INVALID_CREDENTIALS Invalid API key or customer ID Check your credentials
INSUFFICIENT_BALANCE Insufficient account balance Add funds to your account
INVALID_PHONE Invalid phone number format Use 10-digit Mexican format
INVALID_AMOUNT Invalid transaction amount Check min/max limits
INVALID_CARRIER Unsupported carrier Use supported carrier codes
DUPLICATE_REFERENCE Reference already used Use unique references
TRANSACTION_FAILED Transaction failed at provider Check transaction status
RATE_LIMIT_EXCEEDED Too many requests Implement rate limiting
SERVICE_UNAVAILABLE Service temporarily down Retry after delay

Error Handling

Error Response Format

All errors follow this consistent format:

{
  "success": false,
  "error_code": "INVALID_AMOUNT",
  "error_message": "Amount must be between 10 and 500 MXN",
  "transaction_id": "VIA-20251108-001238",
  "timestamp": "2025-11-08T15:55:00Z",
  "details": {
    "field": "amount",
    "value": 5,
    "min": 10,
    "max": 500
  }
}

Best Practices

  1. Always check the success field before processing the response
  2. Log transaction IDs for troubleshooting and reconciliation
  3. Implement retry logic for network errors (with exponential backoff)
  4. Handle timeouts gracefully (some transactions may take 30-60 seconds)
  5. Validate input before sending requests to avoid errors
  6. Monitor webhooks for asynchronous payment confirmations (OXXO, Enefevo)

Retry Strategy

const retryRequest = async (requestFn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await requestFn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      // Don't retry on 4xx errors (except 429)
      if (error.response?.status >= 400 &&
          error.response?.status < 500 &&
          error.response?.status !== 429) {
        throw error;
      }

      // Exponential backoff
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

Rate Limits

To ensure system stability, Via.One implements the following rate limits:

Endpoint Limit Window
All API endpoints 300 requests 15 minutes
Topup endpoints 200 requests 1 minute
Balance inquiry 60 requests 1 minute

Rate Limit Headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 250
X-RateLimit-Reset: 1699459200

When rate limit is exceeded:

{
  "success": false,
  "error_code": "RATE_LIMIT_EXCEEDED",
  "error_message": "Too many requests. Please try again in 5 minutes.",
  "retry_after": 300
}

Webhooks (Optional)

Via.One can send webhook notifications for asynchronous events.

Webhook Events

  • transaction.completed - Transaction successfully completed
  • transaction.failed - Transaction failed
  • oxxo.payment.received - OXXO payment received
  • enefevo.payment.received - Enefevo payment received
  • spei.completed - SPEI transfer completed

Webhook Payload

{
  "event": "transaction.completed",
  "transaction_id": "VIA-20251108-001234",
  "timestamp": "2025-11-08T15:30:05Z",
  "data": {
    "type": "topup",
    "carrier": "MOVISTAR",
    "phone": "5512345678",
    "amount": 50,
    "status": "completed",
    "authorization_code": "AUTH-789456"
  },
  "signature": "sha256=abc123..."
}

Webhook Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
}

Support

Contact Information

Email: support@relier.group Phone: +1 (704) 649-0570 Hours: Monday - Friday, 9:00 AM - 6:00 PM EST

Support Response Times

  • Critical Issues (service outage): 1 hour
  • High Priority (transaction failures): 4 hours
  • Normal Priority (general inquiries): 24 hours
  • Low Priority (feature requests): 48 hours

Documentation and Resources

  • API Documentation: https://docs.via.one/api
  • Integration Guide: https://docs.via.one/integration-guide
  • Status Page: https://status.via.one
  • Changelog: https://docs.via.one/changelog

Changelog

Version 1.0 (November 2025)

  • Initial release
  • Airtime topups for 5 Mexican carriers
  • Bill payments for 100+ service providers
  • SPEI bank transfers
  • OXXO and Enefevo cash payments
  • Real-time transaction status
  • Webhook notifications

© 2025 Via.One - All Rights Reserved

This documentation is confidential and intended solely for authorized customers of Via.One payment services.