API Documentation

Developer Documentation

Welcome to the UniPay API documentation. Build powerful payment experiences with our comprehensive API for MTN MoMo, Airtel Money, and MarzPay.

REST

API Style

JSON

Data Format

<200ms

Response Time

v2.4

API Version

Quick Start

Get started with UniPay in minutes. Our API is designed to be simple and intuitive, with comprehensive SDKs for your favorite programming languages.

Example: Initialize SDK PHP


// Install via Composer
// composer require unipay/unipay-php

require_once 'vendor/autoload.php';

use UniPay\UniPayClient;

// Initialize client
$client = new UniPayClient(
    'sk_live_your_api_key_here',
    [
        'timeout' => 30,
        'environment' => 'live' // or 'sandbox'
    ]
);

// Test connection
try {
    $balance = $client->balance->retrieve();
    echo "Connected successfully! Balance: " . $balance['amount'];
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}


// Install via npm
// npm install @unipay/unipay-node

const UniPay = require('@unipay/unipay-node');

// Initialize client
const client = new UniPay('sk_live_your_api_key_here', {
    timeout: 30000,
    environment: 'live' // or 'sandbox'
});

// Test connection
client.balance.retrieve()
    .then(balance => {
        console.log(`Connected! Balance: ${balance.amount}`);
    })
    .catch(error => {
        console.error('Error:', error.message);
    });


# Install via pip
# pip install unipay-python

import unipay

# Initialize client
client = unipay.Client(
    api_key='sk_live_your_api_key_here',
    timeout=30,
    environment='live'  # or 'sandbox'
)

# Test connection
try:
    balance = client.balance.retrieve()
    print(f"Connected! Balance: {balance['amount']}")
except Exception as e:
    print(f"Error: {str(e)}")


# Test API connection
curl https://api.yourdomain.com/v1/balance \
  -u sk_live_your_api_key_here: \
  -H "Content-Type: application/json"

# Response example:
# {
#   "object": "balance",
#   "amount": 100000,
#   "currency": "UGX",
#   "available": 100000,
#   "pending": 0
# }

Authentication

All API requests must be authenticated using your secret API key. You can find your API keys in the Merchant Dashboard.

Keep your API keys secure

Never commit API keys to version control. Use environment variables in production. Your secret key can perform any API request on your account.

Secret Key

For server-side requests

Used for all server-to-server API requests. Keep this key secure and never expose it in client-side code.

sk_live_51Hq9wKpBvLQ9wYQ...

Publishable Key

For client-side requests

Used for client-side interactions. Safe to include in mobile apps or JavaScript code.

pk_live_51Hq9wKpBvLQ9wYQ...

Making Authenticated Requests


# All API requests must include your API key
# Use HTTP Basic Authentication
curl https://api.yourdomain.com/v1/payments \
  -u sk_live_your_api_key_here: \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "UGX",
    "method": "mtn_momo"
  }'

# Or include in Authorization header
curl https://api.yourdomain.com/v1/payments \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "currency": "UGX"}'

POST

Create a Payment

/v1/payments

Create a new payment transaction. This endpoint returns a payment object with a redirect URL for the customer to complete the payment.

Request

Parameters

Parameter	Type	Required	Description
amount	integer	Required	Amount in smallest currency unit (e.g., cents)
currency	string	Required	Three-letter ISO currency code (UGX, KES, TZS)
method	string	Required	Payment method: mtn_momo, airtel_money, marzpay
phone	string	Optional	Customer phone number (E.164 format)
email	string	Optional	Customer email address
reference	string	Optional	Your internal reference ID
callback_url	string	Optional	Webhook URL for payment notifications
metadata	object	Optional	Additional metadata as key-value pairs


// Example: Create MTN MoMo payment
const payment = await client.payments.create({
  amount: 50000,        // UGX 50,000
  currency: 'UGX',
  method: 'mtn_momo',
  phone: '+256780000000',
  email: 'customer@example.com',
  reference: 'ORDER-12345',
  callback_url: 'https://api.example.com/webhook',
  metadata: {
    order_id: '12345',
    product: 'Premium Subscription'
  }
});

// Response includes redirect URL
console.log(payment.redirect_url);
// Redirect customer to this URL

Response


{
  "id": "pay_7s82hd72nshd92",
  "object": "payment",
  "amount": 50000,
  "currency": "UGX",
  "method": "mtn_momo",
  "status": "pending",
  "redirect_url": "https://pay.yourdomain.com/checkout/pay_7s82hd72nshd92",
  "reference": "ORDER-12345",
  "phone": "+256780000000",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T10:45:00Z",
  "metadata": {
    "order_id": "12345",
    "product": "Premium Subscription"
  }
}

GET

Verify Payment

/v1/payments/{id}

Retrieve a payment object to verify its status. Use this endpoint to check if a payment was successful after redirecting the customer.


// Retrieve payment by ID
const payment = await client.payments.retrieve('pay_7s82hd72nshd92');

// Check payment status
if (payment.status === 'success') {
  // Payment successful, fulfill order
  await fulfillOrder(payment.reference);
} else if (payment.status === 'failed') {
  // Payment failed, notify customer
  showErrorMessage(payment.failure_reason);
}

Payment Statuses

success

Payment completed

pending

Awaiting payment

processing

Being processed

failed

Payment failed

canceled

User canceled

Webhooks

Webhooks allow UniPay to notify your application when events happen in your account. This is especially useful for asynchronous events like payment completions.

Available Events

payment.succeeded

Payment completed successfully

POST

payment.failed

Payment failed or was declined

POST

refund.created

Refund initiated

POST

Webhook Payload Example


{
  "id": "evt_92js8d92jsd9",
  "object": "event",
  "type": "payment.succeeded",
  "data": {
    "object": "payment",
    "id": "pay_7s82hd72nshd92",
    "amount": 50000,
    "currency": "UGX",
    "status": "success",
    "reference": "ORDER-12345",
    "method": "mtn_momo",
    "phone": "+256780000000",
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {
      "order_id": "12345"
    }
  },
  "created": 1705314600,
  "livemode": true
}

Webhook Security

Always verify webhook signatures to ensure requests are from UniPay. Include a secret when creating webhook endpoints.

Ready to integrate?

Start accepting payments in minutes with our comprehensive API documentation and SDKs.

Get API Keys View Examples