UMVA API Documentation

REST API v2.0 - Accept payments, automate withdrawals, manage domains and hosting programmatically.

99.9% Uptime 50+ Endpoints JSON Responses

Introduction

UMVA API provides payment processing, withdrawals, messaging, SEO tools, and infrastructure management through a unified RESTful interface.

Base URL: https://mag.umva.us
Format: JSON
Authentication: API Keys

Authentication

All requests require API keys from your merchant dashboard.

PUBLIC KEY

For initiating payments and public operations

SECRET KEY

For signature validation and secure operations

Never expose your secret key in client-side code or version control.
Test Mode Available: All API endpoints have test mode versions for development. Look for the Test Mode sections throughout this documentation.

Currencies

Supported currencies for global transactions:

Currency Symbol Code Status
United States Dollar $ USD Active
Rwandan Francs R₣ RWF Active
Ghanaian Cedi GH₵ GHS Active
Kenyan Shilling KSh KES Active
Malawian Kwacha K MWK Active
Nigerian Naira NGN Active
Tanzanian Shilling Tsh TZS Active
Ugandan Shilling USh UGX Active
Central African CFA Franc BEAC FCFA XAF Active
CFA Franc CFA XOF Active
BNB Smart Chain (BSC) USDT USDT.BEP20 Active
USDT-TRON USDT USDT.TRC20 Active
Zambian Kwacha ZK ZMW Active

Payment - Overview

Accept payments globally with support for multiple currencies and payment methods. Receive real-time notifications via IPN/webhooks.

Payment Fees

Currency Fixed Charge Percentage Example (100 units)
USDT.TRC20 0 0.6% 0.6
USDT.BEP20 0 0.6% 0.6
KES 0 3.9% 3.9
GHS 0 3.9% 3.9
XOF 0 3.9% 3.9
NGN 0 3.9% 3.9
MWK 0 3.9% 3.9
ZMK 0 3.9% 3.9
USD 0 4.6% 4.6
RWF 0 2.7% 2.7
UGX 0 3.9% 3.9
TZS 0 3.9% 3.9
XAF 0 3.9% 3.9
ZMW 0 3.9% 3.9

Initiate Payment

POST https://mag.umva.us/payment/initiate
Parameters
  • public_key - Your public API key Required
  • identifier - Unique order/transaction reference Required
  • amount - Payment amount Required
  • currency - Currency code (e.g., USD) Required
  • details - Payment description (max 100 chars) Required
  • ipn_url - IPN callback URL Required
  • success_url - Success redirect URL Required
  • cancel_url - Cancel redirect URL Required
  • customer_name - Customer name Optional
  • customer_email - Customer email Optional
cURL Example
curl -X POST 'https://mag.umva.us/payment/initiate' \
  -d 'public_key=YOUR_PUBLIC_KEY' \
  -d 'identifier=ORDER-12345' \
  -d 'amount=100.00' \
  -d 'currency=USD' \
  -d 'details=Payment for order 12345' \
  -d 'ipn_url=https://yoursite.com/ipn' \
  -d 'success_url=https://yoursite.com/success' \
  -d 'cancel_url=https://yoursite.com/cancel'
Response
{
  "success": "ok",
  "message": "Payment Initiated. Redirect to url",
  "url": "https://mag.umva.us/initiate/payment/auth/view/eyJpdiI6..."
}
Note: Redirect the customer to the url provided in the response to complete payment. The URL contains an encrypted payment transaction ID.
Test Mode - Try it Now!

Use the test endpoint for development and testing:

https://mag.umva.us/sandbox/payment/initiate

Test Credentials:

Test Example:

curl -X POST 'https://mag.umva.us/sandbox/payment/initiate' \
  -d 'public_key=YOUR_PUBLIC_KEY' \
  -d 'identifier=TEST-ORDER-001' \
  -d 'amount=100.00' \
  -d 'currency=USD' \
  -d 'details=Test payment' \
  -d 'ipn_url=https://yoursite.com/ipn' \
  -d 'success_url=https://yoursite.com/success' \
  -d 'cancel_url=https://yoursite.com/cancel'

Note: Test mode allows you to test the complete payment flow without processing real transactions. Use the email and code above when prompted during checkout.

Payment Validation

GET https://mag.umva.us/verify/payment?payment_id=PAY-67890
cURL Example
curl -X GET 'https://mag.umva.us/verify/payment?payment_id=PAY-67890&public_key=YOUR_PUBLIC_KEY'
Response
{
  "success": true,
  "data": {
    "payment_id": "PAY-67890",
    "order_id": "ORDER-12345",
    "amount": 100.00,
    "currency": "USD",
    "status": "completed",
    "paid_at": "2025-10-18T10:30:00Z"
  }
}

IPN / Webhooks

Receive POST notifications to your IPN URL when payment status changes.

IPN Payload
{
  "status": "success",
  "signature": "ABC123DEF456...",
  "identifier": "ORDER-12345",
  "data": {
    "payment_trx": "TRX123456789",
    "amount": 100.00,
    "payment_type": "checkout",
    "payment_timestamp": "2025-10-18T10:30:00Z",
    "currency": "USD"
  }
}
Signature Verification
// Signature = HMAC SHA256(amount + identifier, secret_key)
$customKey = $amount . $identifier;
$signature = strtoupper(hash_hmac('sha256', $customKey, YOUR_SECRET_KEY));
if ($signature === $received_signature) {
    // Valid notification
}

Ready-Made Plugins

Quick integration for popular e-commerce platforms.

WooCommerce

One-click installation

Download Plugin
Prestashop

One-click installation

Download Plugin
Whmcs

One-click installation

Download Plugin

Withdrawal - Overview

KYC Required: Complete KYC verification (email, SMS, and documents) before using withdrawal API. Account must be active and verified.
Setup Required: Configure withdrawal methods in merchant dashboard first. Go to Withdraw → Manage Methods to add mobile money or crypto withdrawal methods.

Get Your Saved Withdrawal Methods

GET https://mag.umva.us/api/merchant/withdraw/api/methods

Retrieve all your saved withdrawal methods (mobile money and crypto) with fee structures and limits.

cURL Example
curl -X GET 'https://mag.umva.us/api/merchant/withdraw/api/methods' \
  -H 'X-API-Key: YOUR_PUBLIC_API_KEY'
Response
{
  "success": true,
  "message": "Withdrawal methods retrieved successfully",
  "data": {
    "methods": [],
    "available_currencies": [
      {
        "id": 101,
        "code": "RWF",
        "name": "Rwandan Francs",
        "symbol": "R₣",
        "rate": 0.00068766,
        "type": "mobile_money",
        "providers": [
          {"code": "AIRTEL", "name": "Airtel Money"},
          {"code": "MTN", "name": "MTN Mobile Money"}
        ]
      },
      {
        "id": 104,
        "code": "GHS",
        "name": "Ghanaian Cedi",
        "symbol": "GH₵",
        "rate": 0.09183769,
        "type": "mobile_money",
        "providers": [
          {"code": "AIRTELTIGO", "name": "AirtelTigo Money"},
          {"code": "MTN", "name": "MTN Mobile Money"},
          {"code": "VODAFONE", "name": "Vodafone Cash"}
        ]
      },
      {
        "id": 105,
        "code": "KES",
        "name": "Kenyan Shilling",
        "symbol": "KSh",
        "rate": 0.00774286,
        "type": "mobile_money",
        "providers": [
          {"code": "MPS", "name": "M-Pesa"}
        ]
      },
      {
        "id": 106,
        "code": "MWK",
        "name": "Malawian Kwacha",
        "symbol": "K",
        "rate": 0.0005729,
        "type": "mobile_money",
        "providers": [
          {"code": "AIRTEL", "name": "Airtel Money"}
        ]
      },
      {
        "id": 107,
        "code": "NGN",
        "name": "Nigerian Naira",
        "symbol": "₦",
        "rate": 0.00068061,
        "type": "mobile_money",
        "providers": [
          {"code": "MTN", "name": "MTN Mobile Money"}
        ]
      },
      {
        "id": 109,
        "code": "TZS",
        "name": "Tanzanian Shilling",
        "symbol": "Tsh",
        "rate": 0.00041179,
        "type": "mobile_money",
        "providers": [
          {"code": "AIRTEL", "name": "Airtel Money"},
          {"code": "HALOPESA", "name": "HaloPesa"},
          {"code": "TIGO", "name": "Tigo Pesa"},
          {"code": "VODACOM", "name": "M-Pesa Vodacom"}
        ]
      },
      {
        "id": 110,
        "code": "UGX",
        "name": "Ugandan Shilling",
        "symbol": "USh",
        "rate": 0.00028892,
        "type": "mobile_money",
        "providers": [
          {"code": "AIRTEL", "name": "Airtel Money"},
          {"code": "MTN", "name": "MTN Mobile Money"}
        ]
      },
      {
        "id": 111,
        "code": "XAF",
        "name": "Central African CFA Franc BEAC",
        "symbol": "FCFA",
        "rate": 0.001779,
        "type": "mobile_money",
        "providers": [
          {"code": "MTN", "name": "MTN Mobile Money"},
          {"code": "ORANGEMONEY", "name": "Orange Money"}
        ]
      },
      {
        "id": 112,
        "code": "XOF",
        "name": "CFA Franc",
        "symbol": "CFA",
        "rate": 0.001779,
        "type": "mobile_money",
        "providers": [
          {"code": "MOOV", "name": "Moov Money (Ivory Coast)"},
          {"code": "MTN", "name": "MTN Mobile Money"},
          {"code": "ORANGE", "name": "Orange Money"},
          {"code": "ORANGEMONEY", "name": "Orange Money (Senegal)"},
          {"code": "WAVE", "name": "Wave"}
        ]
      },
      {
        "id": 119,
        "code": "USDT.BEP20",
        "name": "BNB Smart Chain (BSC)",
        "symbol": "USDT",
        "rate": 1,
        "type": "crypto",
        "network": "BEP20",
        "providers": []
      },
      {
        "id": 120,
        "code": "USDT.TRC20",
        "name": "USDT-TRON",
        "symbol": "USDT",
        "rate": 1,
        "type": "crypto",
        "network": "TRC20",
        "providers": []
      }
    ]
  }
}

Calculate Withdrawal Fees

POST https://mag.umva.us/api/merchant/withdraw/api/fees

Calculate exact fees before creating a withdrawal.

Parameters
  • currency - Currency code (e.g., RWF, USDT.TRC20) Required
  • amount - Withdrawal amount Required
cURL Example
curl -X POST 'https://mag.umva.us/api/merchant/withdraw/api/fees' \
  -H 'X-API-Key: YOUR_PUBLIC_API_KEY' \
  -d 'currency=RWF' \
  -d 'amount=50000'
Response
{
  "success": true,
  "message": "Fees calculated successfully",
  "data": {
    "currency": "RWF",
    "currency_symbol": "R₣",
    "amount": 50000,
    "charge": 1000,
    "after_charge": 49000,
    "final_amount": 33.71,
    "rate": 0.00068766
    },
    "min_limit": 1000,
    "max_limit": 5000000
  }
}

Create Withdrawal

POST https://mag.umva.us/api/merchant/withdraw/api/create-direct
Parameters (Mobile Money)
  • currency - Currency code (e.g., RWF, GHS, KES) Required
  • amount - Withdrawal amount Required
  • mobile_number - Mobile number with country code (e.g., +250780123456) Required
  • provider - Mobile money provider (e.g., MTN, AIRTEL) Required
Parameters (Crypto)
  • currency - Currency code (USDT.TRC20 or USDT.BEP20) Required
  • amount - Withdrawal amount Required
  • wallet_address - USDT wallet address Required
  • network - Network (BEP20 or TRC20) Required
💰 Crypto Network Fees:
  • USDT.BEP20: NO FEE (0 USDT charge)
  • USDT.TRC20: 1 USDT fixed charge
cURL Example (Mobile Money)
curl -X POST 'https://mag.umva.us/api/merchant/withdraw/api/create-direct' \
  -H 'X-API-Key: YOUR_PUBLIC_API_KEY' \
  -d 'currency=RWF' \
  -d 'amount=100000' \
  -d 'mobile_number=%2B250780817402' \
  -d 'provider=MTN'
cURL Example (Crypto)
curl -X POST 'https://mag.umva.us/api/merchant/withdraw/api/create-direct' \
  -H 'X-API-Key: YOUR_PUBLIC_API_KEY' \
  -d 'currency=USDT.TRC20' \
  -d 'amount=100' \
  -d 'wallet_address=TYourWalletAddressHere123' \
  -d 'network=TRC20'
Response (Success - Mobile Money Auto-Processed)
{
  "success": true,
  "message": "Withdrawal request created and processed successfully",
  "data": {
    "withdrawal_id": 123,
    "trx": "ABC123XYZ789",
    "amount": 50000,
    "charge": 1000,
    "final_amount": 49000,
    "currency": "RWF",
    "status": "success",
    "created_at": "2025-10-18T10:30:00Z",
    "method_details": {
      "type": "mobile_money",
      "provider": "MTN",
      "network": null
    }
  }
}
Response (Pending - Crypto Processing)
{
  "success": true,
  "message": "Withdrawal is being processed",
  "data": {
    "withdrawal_id": 124,
    "trx": "DEF456GHI012",
    "amount": 100,
    "charge": 1,
    "final_amount": 99,
    "currency": "USDT.TRC20",
    "status": "pending",
    "created_at": "2025-10-18T10:35:00Z",
    "note": "Processing may take a few minutes"
  }
}

Check Withdrawal Status

GET https://mag.umva.us/api/merchant/withdraw/api/status/{trx}

Check the current status of a withdrawal using its transaction reference.

cURL Example
curl -X GET 'https://mag.umva.us/api/merchant/withdraw/api/status/ABC123XYZ789' \
  -H 'X-API-Key: YOUR_PUBLIC_API_KEY'
Response
{
  "success": true,
  "message": "Withdrawal status retrieved successfully",
  "data": {
    "withdrawal_id": 123,
    "trx": "ABC123XYZ789",
    "amount": 50000,
    "charge": 1000,
    "final_amount": 49000,
    "currency": "RWF",
    "status": "success",
    "status_code": 1,
    "created_at": "2025-10-18T10:30:00Z",
    "updated_at": "2025-10-18T10:32:00Z",
    "failure_reason": null,
    "retry_count": 0,
    "method_details": [
      {
        "name": "Mobile Number",
        "type": "text",
        "value": "250788123456"
      },
      {
        "name": "Provider",
        "type": "text",
        "value": "MTN"
      },
      {
        "name": "Provider Name",
        "type": "text",
        "value": "MTN Mobile Money Rwanda"
      },
      {
        "name": "Via API",
        "type": "text",
        "value": "Yes"
      }
    ]
  }
}
Status Values: pending (processing), success (completed), rejected (failed/refunded)

Messaging - Overview

Send WhatsApp and email messages programmatically. Perfect for notifications, marketing, and customer engagement.

Messaging API is currently in beta. Contact support to enable access.

WhatsApp API

POST https://mag.umva.us/api/messaging/whatsapp/send
Parameters
  • api_key - Your API key Required
  • number - Recipient phone number (international format) Required
  • message - Message text Required
cURL Example
curl -X POST 'https://mag.umva.us/api/messaging/whatsapp/send' \
  -d 'api_key=YOUR_API_KEY' \
  -d 'number=250788123456' \
  -d 'message=Hello from UMVA'
Response
{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "device_name": "Device 1",
    "remaining_capacity": 450
  }
}

Email API

POST https://mag.umva.us/api/messaging/email/send
Parameters
  • api_key - Your API key Required
  • email - Recipient email address Required
  • subject - Email subject Required
  • message - Email body (supports HTML) Required
  • reply_to - Reply-to email address Optional
cURL Example
curl -X POST 'https://mag.umva.us/api/messaging/email/send' \
  -d 'api_key=YOUR_API_KEY' \
  -d '[email protected]' \
  -d 'subject=Welcome to our service' \
  -d 'message=Thank you for signing up!' \
  -d '[email protected]'
Response
{
  "success": true,
  "message": "Email sent successfully",
  "data": {
    "server_name": "Email Server 1",
    "remaining_capacity": 95
  }
}

Lab & SEO Tools - Overview 50% OFF

Access social media marketing and SEO services: Instagram, Facebook, YouTube, Twitter/X, TikTok growth services.

Get Services

POST https://mag.umva.us/api/lab
Parameters
  • api_key - Your API key Required
  • action - Must be services Required
cURL Example
curl -X POST 'https://mag.umva.us/api/lab' \
  -d 'api_key=YOUR_API_KEY' \
  -d 'action=services'
Response
[
  {
    "service": 1,
    "name": "Instagram Followers",
    "category": "Instagram",
    "rate": "1.25",
    "min": 100,
    "max": 10000,
    "refill": true,
    "cancel": false,
    "dripfeed": false
  },
  {
    "service": 2,
    "name": "YouTube Views",
    "category": "YouTube",
    "rate": "0.88",
    "min": 1000,
    "max": 100000,
    "refill": false,
    "cancel": false,
    "dripfeed": true
  }
]
Note: Rates shown include 50% API discount already applied.

Place Order

POST https://mag.umva.us/api/lab
Parameters
  • api_key - Your API key Required
  • action - Must be add Required
  • service - Service ID from services list Required
  • link - Target URL/username Required
  • quantity - Order quantity Required
cURL Example
curl -X POST 'https://mag.umva.us/api/lab' \
  -d 'api_key=YOUR_API_KEY' \
  -d 'action=add' \
  -d 'service=1' \
  -d 'link=https://instagram.com/username' \
  -d 'quantity=1000'
Response (Success)
{
  "order": 123456
}
Response (Error)
{
  "error": "Insufficient balance"
}
Important: The order value returned is your API order ID. Use this to check order status.

Check Status

POST https://mag.umva.us/api/lab
Parameters
  • api_key - Your API key Required
  • action - Must be status Required
  • order - API order ID from place order response Required
cURL Example
curl -X POST 'https://mag.umva.us/api/lab' \
  -d 'api_key=YOUR_API_KEY' \
  -d 'action=status' \
  -d 'order=123456'
Response
{
  "charge": "0.00",
  "start_count": "1000",
  "status": "Completed",
  "remains": "0",
  "currency": "USD"
}

Hosting & Domains - Overview 50% OFF

Provision web hosting with cPanel, manage domains, and automate infrastructure deployment.

Get Plans

GET https://mag.umva.us/api/hosting/plans
cURL Example
curl -X GET 'https://mag.umva.us/api/hosting/plans' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "cPanel Basic",
      "type": "cpanel_basic",
      "price_monthly": 4.99,
      "setup_fee": 0,
      "disk_space": "10 GB",
      "bandwidth": "100 GB",
      "accounts": "N/A",
      "domains": 1,
      "databases": "Unlimited",
      "features": ["cPanel", "Email Accounts", "Free SSL"],
      "api_discount": "50% for shared hosting only"
    },
    {
      "id": 2,
      "name": "VPS Basic",
      "type": "vps_basic",
      "price_monthly": 19.99,
      "setup_fee": 0,
      "disk_space": "50 GB SSD",
      "bandwidth": "1 TB",
      "accounts": "N/A",
      "domains": "Unlimited",
      "databases": "Unlimited",
      "features": ["Root Access", "2 CPU", "4 GB RAM"],
      "api_discount": "No discount"
    }
  ],
  "note": "50% API discount applies ONLY to shared hosting (cPanel Basic, Advanced, Reseller). No discount for VPS or other hosting types."
}

Create Hosting

POST https://mag.umva.us/api/hosting/create
Parameters
  • api_key - Your API key Required
  • plan_id - Hosting plan ID Required
  • domain - Domain name Required
  • duration - Billing period in months: 1, 3, 6, or 12 Required
cURL Example
curl -X POST 'https://mag.umva.us/api/hosting/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d 'plan_id=1' \
  -d 'domain=example.com' \
  -d 'duration=12'
Response
{
  "success": true,
  "message": "Hosting purchased successfully with 50% API discount!",
  "data": {
    "hosting_id": 123,
    "domain": "example.com",
    "plan": "cPanel Basic",
    "type": "cpanel",
    "duration": "12 month(s)",
    "amount_charged": 29.94,
    "next_due_date": "2026-10-18",
    "status": "Active",
    "api_discount_applied": "50%",
    "original_price": 59.88,
    "discount_saved": 29.94,
    "cpanel_username": "example123",
    "cpanel_password": "AutoGeneratedPass"
  }
}
50% API Discount: Applies to shared hosting (cPanel Basic, Advanced, Reseller) only. VPS and other hosting types are charged at full price. Duration discounts: 3mo (3%), 6mo (5%), 12mo (10%).

Manage Hosting

Suspend Account
POST https://mag.umva.us/api/hosting/suspend/{id}
curl -X POST 'https://mag.umva.us/api/hosting/suspend/123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response
{
  "success": true,
  "message": "Hosting suspended successfully.",
  "data": {
    "hosting_id": 123,
    "domain": "example.com",
    "status": "Suspended"
  }
}
Unsuspend Account
POST https://mag.umva.us/api/hosting/unsuspend/{id}
curl -X POST 'https://mag.umva.us/api/hosting/unsuspend/123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Terminate Account
POST https://mag.umva.us/api/hosting/terminate/{id}
curl -X POST 'https://mag.umva.us/api/hosting/terminate/123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Renew Hosting
POST https://mag.umva.us/api/hosting/renew/{id}
curl -X POST 'https://mag.umva.us/api/hosting/renew/123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response
{
  "success": true,
  "message": "Hosting renewed successfully for 1 month!",
  "data": {
    "hosting_id": 123,
    "domain": "example.com",
    "period": "1 month(s)",
    "amount_charged": 4.99,
    "new_due_date": "2025-11-18"
  }
}
Note: Renewal uses the same duration as the original purchase. The hosting ID is in the URL path.

Register Domain

POST https://mag.umva.us/api/domain/register
Parameters
  • api_key - Your API key Required
  • domain - Domain name to register Required
  • period - Registration period (1-6 years) Optional (default: 1)
cURL Example
curl -X POST 'https://mag.umva.us/api/domain/register' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d 'domain=example.com' \
  -d 'period=2'
Response
{
  "success": true,
  "message": "Domain registered successfully!",
  "data": {
    "domain_id": 456,
    "domain": "example.com",
    "period": "2 year(s)",
    "amount_charged": 25.98,
    "expiry_date": "2027-10-18",
    "status": "active"
  }
}

Renew Domain

POST https://mag.umva.us/api/domain/renew/{id}
Parameters
  • api_key - Your API key Required
  • period - Renewal period (1-6 years) Required
cURL Example
curl -X POST 'https://mag.umva.us/api/domain/renew/456' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d 'period=1'
Response
{
  "success": true,
  "message": "Domain renewed successfully!",
  "data": {
    "domain": "example.com",
    "period": "1 year(s)",
    "amount_charged": 14.99,
    "new_expiry_date": "2028-10-18"
  }
}

Transfer Domain

POST https://mag.umva.us/api/domain/transfer
Parameters
  • api_key - Your API key Required
  • domain - Domain name to transfer Required
  • epp_code - EPP/Authorization code Required
cURL Example
curl -X POST 'https://mag.umva.us/api/domain/transfer' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d 'domain=example.com' \
  -d 'epp_code=ABC123XYZ789'
Response
{
  "success": true,
  "message": "Domain transfer initiated successfully!",
  "data": {
    "domain_id": 789,
    "domain": "example.com",
    "amount_charged": 12.99,
    "transfer_status": "in_progress",
    "note": "Transfer discounts are not available. Full transfer price applied."
  }
}
Important: Domain transfers do not qualify for API discounts. Full transfer price will be charged.