Skip to content

RISE Holdings Payment API Documentation

Overview

The RISE Holdings Payment API provides comprehensive access to Mexican payment services including mobile topups, bill payments, bank transfers (SPEI), and cash collection services. This RESTful API uses secure authentication and supports real-time transaction processing.

Table of Contents

  1. Authentication
  2. API Endpoints
  3. Account Management
  4. Mobile Topups
  5. Bill Payments
  6. SPEI Bank Transfers
  7. Cash Collection (OXXO & SipeCash)
  8. Response Codes
  9. Error Handling
  10. Webhooks
  11. Testing

Authentication

All API requests require authentication using API keys passed in the request headers.

Authentication Headers

X-API-Key: your_api_key_here
X-Customer-ID: your_customer_id_here
Content-Type: application/json

Your Credentials

Customer ID: RISE_HOLDINGS_001
API Key: [Provided separately]
Secret Key: [Provided separately]

⚠️ Security Note: Never expose your API keys in client-side code or public repositories.

Base URL

Production: https://latcom-fix-production.up.railway.app

Test: Contact support for sandbox environment access

API Endpoints

Account Management

Get Account Balance

Retrieve your current account balance and credit information.

Endpoint: GET /api/balance

Headers: 

X-API-Key: your_api_key
X-Customer-ID: RISE_HOLDINGS_001

Response: 

{
  "success": true,
  "customer_id": "RISE_HOLDINGS_001",
  "company_name": "RISE Holdings",
  "current_balance": 45678.50,
  "credit_limit": 50000.00,
  "available_credit": 50000.00,
  "currency": "USD"
}

Mobile Topups

Send mobile airtime directly to any Mexican phone number.

Available Operators

  • Telcel
  • AT&T
  • Movistar
  • Unefon
  • Virgin Mobile

Get Topup Operators

Endpoint: GET /api/muwe/topup-operators

Response: 

{
  "success": true,
  "count": 5,
  "operators": [
    {
      "name": "Telcel",
      "sku": "4002851028",
      "minAmount": 10,
      "maxAmount": 1000,
      "currency": "MXN"
    }
  ]
}

Process Mobile Topup

Endpoint: POST /api/enviadespensa/topup

Headers: 

X-API-Key: your_api_key
X-Customer-ID: RISE_HOLDINGS_001
Content-Type: application/json

Request Body: 

{
  "phone": "5512345678",
  "amount": 50,
  "reference": "ORDER_12345"
}

Field Descriptions: - phone (string, required): Mexican phone number (10 digits, no country code) - amount (number, required): Topup amount in MXN (min: 10, max: 1000) - reference (string, optional): Your internal reference/order ID

Response: 

{
  "success": true,
  "transactionId": "TXN_1234567890",
  "providerTransactionId": "PROV_9876543210",
  "phone": "5512345678",
  "amount": 50,
  "currency": "MXN",
  "status": "completed",
  "message": "Topup completed successfully",
  "processedAt": "2025-11-17T10:30:00Z",
  "responseTime": 1250
}

Possible Status Values: - completed: Topup successful - pending: Processing - failed: Topup failed

Bill Payments

Pay utilities, services, and other bills in Mexico.

Get Bill Payment Companies

Retrieve the list of available billers and service providers.

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

Response: 

{
  "success": true,
  "count": 100,
  "companies": [
    {
      "name": "CFE (Comisión Federal de Electricidad)",
      "sku": "4000035024",
      "category": "electricity",
      "billerType": "electricity",
      "requiresAccountValidation": true
    },
    {
      "name": "Telmex",
      "sku": "4000037020",
      "category": "landline",
      "billerType": "phone"
    },
    {
      "name": "Sky",
      "sku": "4000040024",
      "category": "satellite",
      "billerType": "tv"
    }
  ]
}

Available Bill Categories

  • Electricity: CFE
  • Water: SIAPA, CESPT, CEA, and municipal water services
  • Gas: Ecogas, Maxigas, Z Gas, etc.
  • Cable/Internet: Megacable, Totalplay, Izzi
  • Satellite TV: Sky, Dish, StarTV
  • Phone: Telmex, Telnor
  • Mobile Postpaid: AT&T, Movistar
  • Tolls: Televia, Mueve DF
  • Government: CDMX services
  • Insurance: Various providers

Check Bill Balance

Check the balance due on a bill before payment.

Endpoint: POST /api/muwe/bill-payment/check-balance

Request Body: 

{
  "accountNumber": "1234567890",
  "companySku": "4000035024"
}

Response: 

{
  "success": true,
  "balance": 856.50,
  "billTotal": 856.50,
  "currency": "MXN",
  "dueDate": "2025-11-25",
  "maxPaymentAmount": 856.50
}

Pay Bill

Process a bill payment.

Endpoint: POST /api/muwe/bill-payment/pay

Request Body: 

{
  "accountNumber": "1234567890",
  "amount": 856.50,
  "companySku": "4000035024",
  "reference": "BILL_PAY_12345"
}

Field Descriptions: - accountNumber (string, required): Bill account/reference number - amount (number, required): Payment amount in MXN - companySku (string, required): Biller SKU from companies list - reference (string, optional): Your internal reference ID

Response: 

{
  "success": true,
  "transactionId": "BILL_1234567890",
  "message": "Bill payment successful",
  "billTotal": 856.50,
  "externalId": "EXT_9876543210",
  "processedAt": "2025-11-17T10:35:00Z",
  "responseTime": 2100
}

SPEI Bank Transfers

Send instant bank transfers to any Mexican bank account using SPEI (Sistema de Pagos Electrónicos Interbancarios).

Send SPEI Transfer

Endpoint: POST /api/spei/transfer

Request Body: 

{
  "clabe": "014180606053616829",
  "amount": 500.00,
  "beneficiaryName": "JUAN PEREZ GARCIA",
  "beneficiaryBank": "Santander",
  "reference": "PAYMENT_ORDER_123",
  "concept": "Payment for services",
  "notifyUrl": "https://your-domain.com/webhooks/spei"
}

Field Descriptions: - clabe (string, required): 18-digit CLABE number (Mexican bank account identifier) - amount (number, required): Transfer amount in MXN (min: 10.00) - beneficiaryName (string, required): Recipient name (must match bank account) - beneficiaryBank (string, optional): Bank name for reference - reference (string, optional): Your internal reference - concept (string, required): Transfer concept/description (max 40 chars) - notifyUrl (string, optional): Webhook URL for payment confirmation

Response: 

{
  "success": true,
  "transactionId": "SPEI_1234567890",
  "trackingKey": "TK_9876543210",
  "clabe": "014180606053616829",
  "amount": 500.00,
  "currency": "MXN",
  "beneficiaryName": "JUAN PEREZ GARCIA",
  "status": "completed",
  "processedAt": "2025-11-17T10:40:00Z",
  "settlementDate": "2025-11-17",
  "responseTime": 3200
}

SPEI Transfer Times: - Business Hours (9 AM - 6 PM, Mon-Fri): Instant (typically under 30 seconds) - Outside Business Hours: Processed in next business day batch - Holidays: Processed on next business day

Important Notes: - SPEI transfers are irreversible once completed - Ensure CLABE and beneficiary name are correct before sending - Transfers are subject to bank fraud detection and may be delayed - Minimum amount: 10 MXN, Maximum: 8,000,000 MXN per transaction

Cash Collection

Generate payment references that customers can pay at convenience stores.

Available Services

  • OXXO: Mexico's largest convenience store chain (20,000+ locations)
  • SipeCash (Enefevo): Alternative cash collection network

OXXO Cash Payment

Generate an OXXO payment voucher that customers can pay at any OXXO store.

Endpoint: POST /api/muwe/cash-collection/create

Request Body: 

{
  "amount": 10000,
  "orderNo": "ORDER_12345",
  "customerId": "CUST_001",
  "service": "OXXO",
  "notifyUrl": "https://your-domain.com/webhooks/oxxo",
  "metadata": {
    "customerEmail": "customer@example.com",
    "orderDescription": "Product purchase"
  }
}

Field Descriptions: - amount (integer, required): Amount in centavos (10000 = 100 MXN, min: 1000, max: 1000000) - orderNo (string, optional): Your order/reference number (auto-generated if not provided) - customerId (string, optional): Your customer identifier - service (string, required): "OXXO" or "ENEFEVO" - notifyUrl (string, optional): Webhook URL for payment notifications - metadata (object, optional): Additional information

Response: 

{
  "success": true,
  "reference": "93000011234567890123",
  "amount": 100.00,
  "currency": "MXN",
  "service": "OXXO",
  "barcode": "https://api.sipelatam.mx/barcode/93000011234567890123",
  "paymentUrl": "https://pay.oxxopay.com/file/93000011234567890123",
  "expiresAt": "2025-11-20T23:59:59Z",
  "instructions": "Present this reference at any OXXO store to complete payment"
}

OXXO Payment Instructions for Your Customers: 1. Go to any OXXO store in Mexico 2. Tell the cashier you want to make an OXXO payment 3. Provide the reference number: 93000011234567890123 4. Pay the exact amount in cash 5. Keep your receipt as proof of payment

OXXO Limits: - Minimum: 10 MXN (1000 centavos) - Maximum: 10,000 MXN (1000000 centavos) per transaction - Voucher expiration: 72 hours (3 days)

SipeCash (Enefevo) Payment

Generate a SipeCash/Enefevo payment reference for alternative cash collection points.

Endpoint: POST /api/muwe/cash-collection/create

Request Body: 

{
  "amount": 15000,
  "orderNo": "ORDER_12346",
  "customerId": "CUST_002",
  "service": "ENEFEVO",
  "notifyUrl": "https://your-domain.com/webhooks/sipecash"
}

Response: 

{
  "success": true,
  "reference": "ENEFEVO_1234567890",
  "amount": 150.00,
  "currency": "MXN",
  "service": "ENEFEVO",
  "paymentUrl": "https://pay.enefevo.com/ref/ENEFEVO_1234567890",
  "expiresAt": "2025-11-20T23:59:59Z",
  "instructions": "Present this reference at participating stores"
}

SipeCash (Enefevo) Limits: - Minimum: 10 MXN - Maximum: 10,000 MXN per transaction - Voucher expiration: 72 hours

Check Payment Status

Check the status of a cash collection payment.

Endpoint: GET /api/muwe/cash-collection/status/:reference

Response: 

{
  "success": true,
  "reference": "93000011234567890123",
  "status": "paid",
  "amount": 100.00,
  "paidAt": "2025-11-17T14:30:00Z",
  "paidAmount": 100.00
}

Status Values: - pending: Waiting for payment - paid: Payment completed - expired: Voucher expired without payment - cancelled: Payment cancelled

Response Codes

HTTP Code Meaning
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Endpoint doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error
503 Service Unavailable - Temporary maintenance

Error Handling

All error responses follow this format:

{
  "success": false,
  "error": "Description of what went wrong",
  "code": "ERROR_CODE",
  "details": {
    "field": "Specific error details"
  }
}

Common Error Codes

  • INVALID_API_KEY: API key is missing or invalid
  • INSUFFICIENT_BALANCE: Account balance too low
  • INVALID_PHONE: Phone number format is invalid
  • INVALID_CLABE: CLABE number is invalid
  • AMOUNT_TOO_LOW: Amount below minimum threshold
  • AMOUNT_TOO_HIGH: Amount exceeds maximum threshold
  • SERVICE_UNAVAILABLE: Provider temporarily unavailable
  • DUPLICATE_REFERENCE: Reference ID already used

Webhooks

Receive real-time notifications when payments are completed.

Webhook Configuration

Contact support to configure your webhook URLs.

Webhook Payload

{
  "event": "payment.completed",
  "transactionId": "TXN_1234567890",
  "reference": "YOUR_REF_123",
  "amount": 100.00,
  "currency": "MXN",
  "status": "completed",
  "service": "OXXO",
  "paidAt": "2025-11-17T14:30:00Z",
  "metadata": {
    "customerId": "CUST_001"
  }
}

Webhook Events

  • payment.completed: Payment successfully processed
  • payment.failed: Payment attempt failed
  • payment.expired: Payment voucher expired
  • transfer.completed: SPEI transfer completed
  • transfer.returned: SPEI transfer returned by bank

Webhook Security

All webhooks include a signature header for verification:

X-Webhook-Signature: sha256=abc123...

Verification Example (Node.js): 

const crypto = require('crypto');

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

Testing

Test Credentials

Use your production credentials. All test transactions will be clearly marked in the dashboard and will not affect real accounts.

Test Data

Test Phone Numbers

  • 5512345678 - Always succeeds
  • 5512345679 - Always fails (insufficient balance)
  • 5512345680 - Returns pending status

Test CLABE Numbers

  • 014180606053616829 - Test Santander account (always succeeds in test mode)
  • 012180001234567897 - Test BBVA account (simulates delay)

Test Bill Accounts

  • Use any 10-12 digit number in test mode
  • Results will be simulated

Rate Limits

  • Production: 100 requests per minute per API key
  • Burst: Up to 200 requests per minute for short periods

Support

For technical support, questions, or to report issues:

  • Email: support@riseholdings.com
  • Technical Docs: Contact your account manager
  • Emergency Support: Available 24/7 for production issues

Changelog

Version 1.0.0 (November 2025)

  • Initial API release
  • Mobile topups support
  • Bill payments support
  • SPEI transfers support
  • OXXO cash collection support
  • SipeCash (Enefevo) support

Best Practices

  1. Idempotency: Always include a unique reference in your requests to prevent duplicate charges
  2. Error Handling: Implement retry logic with exponential backoff for failed requests
  3. Webhooks: Use webhooks for payment confirmations instead of polling
  4. Security: Never log or store API keys in plain text
  5. Testing: Test thoroughly in test mode before going live
  6. Monitoring: Monitor your API usage and error rates in the dashboard

API Libraries

Currently, we provide a REST API. Client libraries for popular languages coming soon:

  • Node.js / JavaScript
  • Python
  • PHP
  • Java
  • C# / .NET

For now, use any HTTP client library in your preferred language.

© 2025 RISE Holdings Payment API - All Rights Reserved

This documentation is confidential and intended only for RISE Holdings authorized personnel.