UMVA - Developer Documentation

Payment API Overview

PAYMENT API (FIAT, CRYPTO & HOSTED)

Base URL (Server API): https://umva.net/api/server-api-payment

Authentication & Permissions: For all server payment endpoints, you authenticate by including your public_key (Live or Test) in the JSON request body. Every successful charge or checkout automatically credits your merchant wallet and creates a financial transaction in your account history. Error conditions (invalid keys, invalid payload, insufficient balance, etc.) are returned as JSON error responses with appropriate HTTP status codes.

Standard Request Rules

All endpoints below are POST requests, unless otherwise specified.
All requests must have a JSON body and must include public_key (unless stated otherwise).
Headers must include Content-Type: application/json and Accept: application/json.

Standard Response Formats

All server payment API responses follow a consistent JSON schema using the status field:

{
  "status": "success",
  "message": "Action successful description.",
  "data": { ... } // Optional extra data
}

Error responses typically use HTTP status codes 400, 401, 404 or 500 and follow this structure:

{
  "status": "error",
  "error": "Error description."
}

High-Level Flows:

Fiat (Mobile Money): Create Customer → (optional) Get Customer → Create Payment Gateway → (optional) Get Gateways → Initiate Fiat Charge → IPN confirms and credits merchant.
Crypto: Get Gateways (crypto) → Initiate Crypto Charge (returns address) → Customer sends crypto → IPN confirms and credits merchant.
Hosted Checkout (Web): Initiate hosted payment via web endpoint → Redirect customer to hosted checkout URL → Customer completes payment via card, mobile money, crypto, or UMVA account balance → IPN and redirects used for result.

Endpoint Index

All server API payment endpoints are prefixed with /api/server-api-payment:

POST /create-customer
POST /get-customer
POST /create-payment-gateway
POST /get-gateways
POST /initiate-fiat
POST /initiate-crypto
POST /check-payment-status
POST /hosted-payment

API payments table (api_payments)

All server API and hosted payments are stored in the api_payments table. Key columns:

Column	Purpose
`id`	Primary key.
`trx`	Internal UMVA transaction reference (e.g. UMV-TRX-…).
`identifier`	Your order reference; used for IPN verification and `/check-payment-status`.
`merchant_id`	Merchant that receives the payment.
`currency_id`	Currency of the payment.
`amount`	Payment amount.
`ipn_url`	Callback URL for payment confirmation (IPN). Stored when provided on initiate.
`success_url`	URL to redirect payer after successful payment.
`cancel_url`	URL to redirect payer if payment is cancelled or fails.
`gateway_charge_id`	Provider charge ID after charge is created.
`crypto_address`	Generated crypto address for crypto payments.
`status`	0 = pending, 1 = success, 2 = failed.
`type`	e.g. `live`.
`details`	Optional text (e.g. crypto coin/network).
`site_logo`, `checkout_theme`	Hosted checkout options.
`customer_name`, `customer_email`	Payer display info (hosted flow).
`created_at`, `updated_at`	Timestamps.

success_url and cancel_url: The server API accepts and stores these on /initiate-fiat and /initiate-crypto. They are returned in the initiate responses and in /check-payment-status.

Getting Started

Domains

SMM | Lab (SEO)

Hosted Payments

Crypto Payments

Messaging

WhatsApp API

Email API

IPTV