Skip to content

MobiSend D2C API Documentation

Base URL: https://app.via.one/api/mobisend Version: 1.0 Authentication: API Key via x-api-key header

Authentication

All requests require the x-api-key header:

x-api-key: your_api_key_here

Your API key will be provided during onboarding. Keep it secret — it authenticates all requests and is tied to your balance.

Rate Limits

  • 120 requests/minute per API key
  • Exceeding the limit returns HTTP 429

Endpoints

1. GET / — API Status

Returns API info and available endpoints.

curl -H "x-api-key: YOUR_KEY" https://app.via.one/api/mobisend/

2. GET /providers — Available Countries & Carriers

Returns all countries with active products, grouped by carrier.

curl -H "x-api-key: YOUR_KEY" https://app.via.one/api/mobisend/providers

Response: 

{
  "success": true,
  "countries": {
    "MX": {
      "carriers": [
        { "name": "Telcel", "products": 45 },
        { "name": "Movistar", "products": 12 },
        { "name": "AT&T", "products": 15 }
      ],
      "total_products": 72,
      "provider": "CODIGOARIX"
    },
    "HN": { ... },
    "PH": { ... }
  },
  "total_countries": 107
}

3. GET /catalog/:country — Product Catalog

Returns all products for a country, grouped by carrier.

curl -H "x-api-key: YOUR_KEY" https://app.via.one/api/mobisend/catalog/MX

Response: 

{
  "success": true,
  "country": "MX",
  "carriers": {
    "Telcel": [
      { "product_id": 123, "name": "Recarga $50", "amount": 50, "currency": "MXN", "type": "topup" },
      { "product_id": 124, "name": "Paquete Internet 2GB", "amount": 100, "currency": "MXN", "type": "bundle" }
    ],
    "Movistar": [ ... ],
    "AT&T": [ ... ]
  },
  "total_products": 72
}

4. GET /catalog/:country/:carrier — Carrier-Specific Products

curl -H "x-api-key: YOUR_KEY" https://app.via.one/api/mobisend/catalog/MX/Telcel

5. GET /billers — Search Bill Payment Billers

Search and browse available billers for bill payments (75K+ billers via CellPay).

Query Parameters: | Param | Type | Description | |-------|------|-------------| | search | string | Search biller name (e.g., "AT&T", "Electric") | | country | string | Filter by country code (e.g., "US", "MX") | | category | string | Filter by category (e.g., "electric", "cable") | | page | number | Page number (default: 1) | | limit | number | Results per page (default: 50, max: 200) |

curl -H "x-api-key: YOUR_KEY" \
  "https://app.via.one/api/mobisend/billers?search=electric&country=US&limit=20"

Response: 

{
  "success": true,
  "billers": [
    {
      "id": 456,
      "biller_code": "12345",
      "name": "Duke Energy",
      "category": "electric",
      "country": "US",
      "rush_available": true,
      "provider": "cellpay"
    }
  ],
  "pagination": {
    "total": 1200,
    "page": 1,
    "limit": 20,
    "pages": 60
  }
}

6. GET /balance — Account Balance

curl -H "x-api-key: YOUR_KEY" https://app.via.one/api/mobisend/balance

Response: 

{
  "success": true,
  "account": {
    "customer_id": "MOBISEND_001",
    "company_name": "MobiSend",
    "balance_usd": 5000.00,
    "reserved_usd": 0.00,
    "available_usd": 5000.00,
    "credit_limit_usd": 0.00,
    "currency": "USD"
  }
}

7. POST /topup — Process Mobile Topup

Send a mobile topup to any supported country/carrier.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | phone | string | Yes | Phone number (digits only, no country code) | | amount | number | Yes | Amount in local currency (MXN for Mexico, USD for international) | | country | string | No | ISO country code (default: MX) | | carrier | string | No | Carrier name (auto-detected if omitted for MX) | | sku | string | No | Specific product SKU (overrides carrier routing) | | reference | string | No | Your internal reference ID | | type | string | No | topup or bundle (default: auto-detect) |

Mexico Example: 

curl -X POST -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5512345678",
    "amount": 100,
    "country": "MX",
    "carrier": "Telcel"
  }' \
  https://app.via.one/api/mobisend/topup

International Example (Honduras): 

curl -X POST -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "98765432",
    "amount": 5,
    "country": "HN",
    "carrier": "Tigo"
  }' \
  https://app.via.one/api/mobisend/topup

Success Response: 

{
  "success": true,
  "order": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "SUCCESS",
    "type": "topup",
    "phone": "5512345678",
    "country": "MX",
    "carrier": "Telcel",
    "amount": 100,
    "currency": "MXN",
    "amount_usd": 6.02,
    "exchange_rate": 17.50,
    "provider_reference": "ABC123",
    "processed_at": "2026-04-21T15:30:00.000Z"
  },
  "billing": {
    "deducted_usd": 6.02,
    "balance_before_usd": 5000.00,
    "balance_after_usd": 4993.98
  }
}

Failure Response: 

{
  "success": false,
  "error": "NO SE PUEDE ABONAR A ESTE NUMERO",
  "order": {
    "id": "a1b2c3d4-...",
    "status": "FAILED",
    "phone": "5512345678",
    "country": "MX",
    "amount": 100,
    "currency": "MXN"
  }
}

8. POST /billpay — Process Bill Payment

Pay a bill through CellPay's 75K+ biller network.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | biller_id | string | Yes | Biller code (from /billers endpoint) | | account_number | string | Yes | Customer account number | | amount | number | Yes | Payment amount in USD | | rush | boolean | No | Same-day processing (default: false) | | reference | string | No | Your internal reference | | first_name | string | No | Account holder first name | | last_name | string | No | Account holder last name | | zip_code | string | No | Account holder zip code |

Fees: - Standard (next-day): $0.75 USD per transaction - Rush (same-day): $1.25 USD per transaction

curl -X POST -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "biller_id": "12345",
    "account_number": "1234567890",
    "amount": 150.00,
    "rush": false,
    "reference": "INV-2026-001"
  }' \
  https://app.via.one/api/mobisend/billpay

Success Response: 

{
  "success": true,
  "order": {
    "id": "b2c3d4e5-...",
    "status": "SUCCESS",
    "type": "billpay",
    "biller": "Duke Energy",
    "account_number": "1234567890",
    "amount_usd": 150.00,
    "fee_usd": 0.75,
    "total_usd": 150.75,
    "rush": false,
    "confirmation_code": "BP789012",
    "processed_at": "2026-04-21T15:30:00.000Z"
  },
  "billing": {
    "deducted_usd": 150.75,
    "balance_before_usd": 5000.00,
    "balance_after_usd": 4849.25
  }
}

9. GET /order/:id — Order Status

Look up any order by transaction ID.

curl -H "x-api-key: YOUR_KEY" \
  https://app.via.one/api/mobisend/order/a1b2c3d4-e5f6-7890-abcd-ef1234567890

10. GET /orders — Order History

Paginated order history with optional filters.

Query Parameters: | Param | Type | Description | |-------|------|-------------| | start_date | string | Start date YYYY-MM-DD | | end_date | string | End date YYYY-MM-DD | | status | string | Filter by status: success, failed | | limit | number | Results per page (default: 50, max: 200) | | offset | number | Pagination offset |

curl -H "x-api-key: YOUR_KEY" \
  "https://app.via.one/api/mobisend/orders?start_date=2026-04-01&end_date=2026-04-21&limit=20"

Idempotency

All POST endpoints support idempotency. Include the Idempotency-Key header to prevent duplicate transactions:

curl -X POST -H "x-api-key: YOUR_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5512345678", "amount": 100, "country": "MX"}' \
  https://app.via.one/api/mobisend/topup

If the same Idempotency-Key is sent within 24 hours, you'll receive the original response without re-processing.

Error Codes

HTTP Status Meaning
200 Success (check success field — can be false for provider rejections)
400 Bad request — missing or invalid parameters
401 Invalid or missing API key
403 Insufficient balance or IP not authorized
404 Resource not found
429 Rate limit exceeded
500 Server error

Common Provider Errors (in error field)

Error Meaning
NO SE PUEDE ABONAR A ESTE NUMERO Subscriber rejection (invalid number or carrier mismatch)
POSIBLE DUPLICADO Anti-fraud: duplicate detected. Wait 5 min and retry
Insufficient balance Top up your MobiSend account
Phone must be X digits Wrong phone format for the country

Supported Countries & Providers

Country Carriers Provider Currency
MX Telcel, AT&T, Movistar, Unefon, Virgin, BAIT, 17+ MVNOs Codigo Arix / Altamira MXN
HN Claro, Digicel, Tigo PPN (ValueTopup) USD
PH Globe, Smart, TNT, Sun, DITO, GOMO, TM PPN USD
PE Bitel, Entel, Claro, Movistar PPN USD
VE Movistar, Digitel, Movilnet Servipagos USD
107+ countries All major carriers PPN USD
US/Intl 75K+ billers CellPay USD

Webhooks (Coming Soon)

Webhook support for real-time order status notifications is planned. Contact support for early access.

Support

  • Email: api-support@mobisend.com
  • Technical Contact: Richard Mas (richard@via.one)
  • Status Page: app.via.one/health