LivePay API Documentation

Overview

The Collection API allows you to initiate mobile money collections from customers. When a collection is initiated, the customer receives a prompt on their phone to approve the payment.

Endpoint

https://livepay.me/api/v1/collect-money

Method: POST

Quick Start

Request Example

Terminal

curl -X POST "https://livepay.me/api/v1/collect-money" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <--your-secret-key-->" \
  -d '{
    "apikey": "<--your-public-key-->",
    "reference": "52750by31220ffbc7de3b36",
    "phone_number": "256702069536",
    "amount": 500,
    "currency": "UGX",
    "network": "AIRTEL"
  }'

Authentication

All API requests require Bearer token authentication using your Secret Key in the Authorization header, and your Public Key in the request body.

Headers

Authorization

Bearer <--your-secret-key-->

Content-Type

application/json

Body Parameters

apikey

<--your-public-key-->

Request Parameters

Parameter	Type	Required	Description
`apikey`	String	Yes	Your public API key
`reference`	String	Yes	Your unique reference ID (prevents duplicates)
`phone_number`	String	Yes	Customer's phone number (e.g., 256702069536)
`amount`	Number	Yes	Amount to collect (subject to min/max per currency)
`currency`	String	Yes	e.g., UGX
`network`	String	Yes	e.g., AIRTEL

Response Format

Success Response (201 Created)

success.json

{
  "status": "success",
  "message": "Collection initiated successfully",
  "data": {
    "reference": "52750by31220ffbc7de3b36",
    "transaction_id": "67d4c8f3a1b29",
    "amount": 500,
    "currency": "UGX",
    "network": "AIRTEL"
  }
}

Error Responses

Status Code	Response	Description
400	{ "status": "error", "message": "Missing required fields: amount, phone_number" }	Missing required fields
400	{ "status": "error", "message": "Currency not supported" }	Currency not supported
400	{ "status": "error", "message": "Invalid network for UGX. Available networks: AIRTEL, MTN" }	Invalid network for currency
400	{ "status": "error", "message": "Amount must be at least 500 for UGX" }	Amount below minimum
400	{ "status": "error", "message": "Amount cannot exceed 5000000 for UGX" }	Amount above maximum
401	{ "status": "error", "message": "Invalid API key" }	Invalid secret key
401	{ "status": "error", "message": "Invalid or unauthorized public key" }	Invalid public key
403	{ "status": "error", "message": "Currency not activated" }	Currency not activated for your account
403	{ "status": "error", "message": "Unauthorized. Complete KYC to access this API" }	KYC not complete
403	{ "status": "error", "message": "API access is turned off by user" }	API access disabled in settings
404	{ "status": "error", "message": "User not found" }	User account not found
405	{ "status": "error", "message": "Method Not Allowed" }	Only POST method allowed
409	{ "status": "error", "message": "Duplicate reference detected" }	Reference already used
500	{ "status": "error", "message": "CURL Error: Failed to connect" }	Network or Payaza API error

Code Examples

javascript.js

async function initiateCollection(data) {
    const response = await fetch('https://livepay.me/api/v1/collect-money', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer <--your-secret-key-->'
        },
        body: JSON.stringify({
            apikey: '<--your-public-key-->',
            reference: data.reference,
            phone_number: data.phone_number,
            amount: data.amount,
            currency: data.currency,
            network: data.network
        })
    });
    
    if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message);
    }
    
    return await response.json();
}

Important Notes

Customer Approval Required

The customer must approve the payment on their phone.

Currency Activation

Each currency must be activated for your account.

Duplicate Prevention

Each reference ID can only be used once.