Lyntra Payments API

Welcome to the Lyntra Payments API documentation. Our REST API lets you integrate mobile money collections and disbursements via MTN Mobile Money and Airtel Money across Uganda.

How the API Works

All requests use standard HTTP methods (GET, POST, PATCH, DELETE) and return JSON responses. Authentication uses API keys passed in the Authorization header.

Request Format

POST /v1/collections/initiate HTTP/1.1
Host: api.lyntra.com
Authorization: Bearer pgk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{"msisdn": "256771234567", "amount": "10000", ...}

Response Format

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference": "LYN_20240326_XYZ789",
  "status": "PENDING",
  "amount": "10000",
  "currency": "UGX",
  "created_at": "2024-03-26T10:00:00Z"
}

Error Format

{
  "error": {
    "code": "INVALID_MSISDN",
    "message": "The provided phone number is not a valid MTN number",
    "request_id": "req_abc123"
  }
}

Authentication

All API requests require an API key passed in the HTTP Authorization header as a Bearer token.

API Key Types

• Sandbox keys — prefix pgk_sandbox_ — safe for testing, no real money moves
• Production keys — prefix pgk_live_ — live transactions, real money

Scopes

API keys have scopes that control what operations they can perform:

Example Header

Authorization: Bearer pgk_sandbox_b9ac76b458a85f8bd15d9e276a14bb8f7c3f127a498386593b5b124023e96d60

Getting API Keys

API keys are generated from your dashboard under API Keys. You can create multiple keys with different scopes and environments. Production keys require KYC verification.

Quick Start

Get your first payment collection running in under 5 minutes.

Step 1 — Get your API key

Log in to your dashboard, navigate to API Keys, and create a sandbox key with collections:write scope.

Step 2 — Get your Business Account ID

Go to Business Accounts in your dashboard and copy the ID of the account you want to receive payments into. Business accounts act as virtual wallets — credits from collections and debits from disbursements are tracked against them.

Step 3 — Initiate a collection

The correct mobile money provider (MTN or Airtel) is automatically detected from the customer's phone number — you do not need to specify it.

const API_KEY = 'pgk_sandbox_your_key_here';
const ACCOUNT_ID = 'your_business_account_id';

const res = await fetch('https://staging.lyntraengineering.com/v1/collections/initiate', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    msisdn: '256771234567',   // MTN auto-detected from 0771 prefix
    amount: '5000',           // Amount in UGX
    currency: 'UGX',
    reference: 'ORDER-1234',   // Your unique reference
    business_account_id: ACCOUNT_ID,
    description: 'Payment for Order #1234'
  })
});
const data = await res.json();
console.log(data.reference); // Save this to check status later

import requests

API_KEY = 'pgk_sandbox_your_key_here'
ACCOUNT_ID = 'your_business_account_id'

r = requests.post(
    'https://staging.lyntraengineering.com/v1/collections/initiate',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'msisdn': '256771234567',   # MTN auto-detected from 0771 prefix
        'amount': '5000',
        'currency': 'UGX',
        'reference': 'ORDER-1234',
        'business_account_id': ACCOUNT_ID,
        'description': 'Payment for Order #1234'
    }
)
data = r.json()
print(data['reference'])  # Save to check status

$apiKey = 'pgk_sandbox_your_key_here';
$accountId = 'your_business_account_id';

$ch = curl_init('https://staging.lyntraengineering.com/v1/collections/initiate');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$apiKey}", 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'msisdn' => '256771234567',   // MTN auto-detected
        'amount' => '5000',
        'currency' => 'UGX',
        'reference' => 'ORDER-1234',
        'business_account_id' => $accountId,
        'description' => 'Payment for Order #1234'
    ])
]);
$data = json_decode(curl_exec($ch), true);
echo $data['reference']; // Save to check status

curl -X POST https://staging.lyntraengineering.com/v1/collections/initiate \
  -H "Authorization: Bearer pgk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "256771234567",
    "amount": "5000",
    "currency": "UGX",
    "reference": "ORDER-1234",
    "business_account_id": "your_account_id",
    "description": "Payment for Order #1234"
  }'

Step 4 — Handle the webhook

When the customer pays (or the transaction fails), Lyntra sends a POST request to your callback_url:

{
  "event": "collection.successful",
  "data": {
    "reference": "LYN_20240326_XYZ789",
    "status": "SUCCESSFUL",
    "amount": "5000",
    "msisdn": "256771234567",
    "provider_txn_id": "MTN_TXN_987654"
  },
  "timestamp": "2024-03-26T10:05:23Z",
  "signature": "sha256=abc123..."
}

Sandbox Testing

The sandbox mimics the full production behaviour. Use these test numbers to simulate different outcomes:

Set environment: "SANDBOX" in all requests during testing. Switch to "PRODUCTION" when you go live.

Collections

Collections let you request a payment from a customer's mobile money wallet. The customer receives a USSD prompt to approve the payment.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference": "LYN_20240326_ABC123",
  "status": "PENDING",
  "type": "COLLECTION",
  "provider": "MTN",
  "msisdn": "256771234567",
  "amount": "5000",
  "currency": "UGX",
  "fee": "75",
  "net_amount": "4925",
  "initiated_at": "2024-03-26T10:00:00Z"
}

{
  "reference": "LYN_20240326_ABC123",
  "status": "SUCCESSFUL",
  "provider_txn_id": "MTN_TXN_987654",
  "completed_at": "2024-03-26T10:02:45Z",
  "amount": "5000", "fee": "75", "net_amount": "4925"
}

Disbursements

Disbursements let you send money to any MTN or Airtel mobile money number. Use this for payroll, refunds, agent commissions, and bulk payouts.

const res = await fetch('https://api.lyntra.com/v1/disbursements/initiate', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    msisdn: '256771234567',    // MTN auto-detected from 0771 prefix
    amount: '10000',
    currency: 'UGX',
    reference: 'SALARY-MAR-2024-001',
    business_account_id: accountId,
    recipient_name: 'John Doe',
    description: 'Salary payment March 2024'
  })
});

r = requests.post('https://api.lyntra.com/v1/disbursements/initiate',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'msisdn': '256771234567',    # MTN auto-detected
        'amount': '10000',
        'currency': 'UGX',
        'reference': 'SALARY-MAR-2024-001',
        'business_account_id': account_id,
        'recipient_name': 'John Doe',
        'description': 'Salary payment'
    })

$res = json_decode(file_get_contents('https://api.lyntra.com/v1/disbursements/initiate',
  false, stream_context_create(['http' => [
    'method'  => 'POST',
    'header'  => "Authorization: Bearer {$apiKey}\r\nContent-Type: application/json",
    'content' => json_encode([
      'msisdn'            => '256771234567',    // MTN auto-detected
      'amount'            => '10000',
      'currency'          => 'UGX',
      'reference'         => 'SALARY-MAR-2024-001',
      'business_account_id' => $accountId,
      'recipient_name'    => 'John Doe',
    ])]])), true);

KYC — Know Your Customer

KYC endpoints let you verify mobile money subscribers before initiating transactions. Results are cached for 24 hours to reduce provider calls. Requires the kyc:read scope.

{
  "msisdn": "256771234567",
  "first_name": "John",
  "last_name": "Doe",
  "gender": "M",
  "birthdate": "1990-01-15",
  "is_active": true,
  "is_barred": false,
  "is_pin_set": true,
  "registration_status": "REGISTERED",
  "provider": "MTN"
}

{
  "msisdn": "256771234567",
  "can_transact": true,
  "is_active": true,
  "is_barred": false
}

Business Accounts

Business accounts are virtual wallets that track your transaction flows. Credits from successful collections and debits from disbursements are recorded against the account's shadow ledger.

[
  {
    "id": "ba_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "Main Operations",
    "currency": "UGX",
    "is_active": true,
    "created_at": "2024-03-26T09:00:00Z"
  }
]

Balance

{
  "business_account_id": "ba_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "account_name": "Main Operations",
  "currency": "UGX",
  "providers": [
    {
      "provider": "MTN",
      "account_type": "COLLECTION",
      "shadow_balance": 2500000
    },
    {
      "provider": "MTN",
      "account_type": "DISBURSEMENT",
      "shadow_balance": 750000
    },
    {
      "provider": "AIRTEL",
      "account_type": "COLLECTION",
      "shadow_balance": 980000
    }
  ]
}

Webhooks

Lyntra Payments sends real-time webhook events to your callback_url when transaction statuses change. This is the recommended way to track payment outcomes.

Webhook Events

Webhook Payload

{
  "event": "collection.successful",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference": "LYN_20240326_ABC123",
    "status": "SUCCESSFUL",
    "type": "COLLECTION",
    "provider": "MTN",
    "msisdn": "256771234567",
    "amount": "5000",
    "currency": "UGX",
    "fee": "75",
    "net_amount": "4925",
    "provider_txn_id": "MTN_TXN_987654",
    "completed_at": "2024-03-26T10:02:45Z"
  },
  "timestamp": "2024-03-26T10:02:46Z",
  "signature": "sha256=4ac3f7e89b1234567890abcdef123456"
}

Verifying Webhook Signatures

Each webhook includes a signature header computed as HMAC-SHA256(payload, webhook_secret). Always verify this before processing.

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signatureHeader)
  );
}

// Express.js example
app.post('/webhooks', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-lyntra-signature'];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // Process event...
  res.sendStatus(200);
});

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask example
from flask import Flask, request, abort
app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def webhook():
    sig = request.headers.get('X-Lyntra-Signature', '')
    if not verify_webhook(request.data, sig, WEBHOOK_SECRET):
        abort(401)
    event = request.get_json()
    # Process event...
    return '', 200

function verifyWebhook($rawBody, $signature, $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

$rawBody = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_LYNTRA_SIGNATURE'] ?? '';

if (!verifyWebhook($rawBody, $sig, $webhookSecret)) {
    http_response_code(401);
    exit('Invalid signature');
}
$event = json_decode($rawBody, true);
// Process $event...
http_response_code(200);

Error Codes

API Keys

Create and manage API keys from your dashboard under API Keys. Each key has a set of scopes and is bound to an environment (sandbox or production).

{
  "id": "3fa85f64-...",
  "name": "Production Key",
  "raw_key": "pgk_live_xxxxxxxxxxxxxxxxxxxxxxxx",  // Only shown once!
  "key_prefix": "pgk_live_xxxx",
  "scopes": ["collections:write", "collections:read"],
  "environment": "PRODUCTION",
  "is_active": true
}

Providers & Networks

The correct mobile money provider is automatically selected based on the customer's phone number prefix. You never specify a provider explicitly in collection or disbursement requests.

Platform-Managed Credentials

MTN and Airtel API credentials (client ID, client secret, subscription keys) are stored at the platform level. All business accounts share these platform provider configurations — there is no per-company or per-account credential management.

Transaction Statuses

SDKs & Libraries

Official SDKs coming soon. Until then, use the REST API directly with the code examples above.

Changelog

v1.1 — March 2026

• Platform-level provider configs — MTN and Airtel credentials are now managed centrally by Lyntra. Companies no longer configure per-account provider credentials.
• Automatic provider detection — The provider and environment fields have been removed from collection and disbursement request bodies. The correct provider is selected automatically from the phone number prefix.
• KYC endpoints — New GET /v1/kyc/{msisdn} for full subscriber lookup and GET /v1/kyc/{msisdn}/validate for quick transaction eligibility checks. Results cached for 24 hours.
• Disbursement sync — New POST /v1/disbursements/{reference}/sync endpoint to manually poll the provider for the latest status.
• Per-provider balance breakdown — GET /v1/balance/{business_account_id} now returns balances split by provider and account type (collection vs disbursement).

v1.0 — January 2026

• Initial release of Lyntra Payments API
• MTN Mobile Money collections and disbursements
• Airtel Money collections and disbursements
• Real-time webhooks with HMAC signature verification
• Sandbox environment for testing
• Business account management
• Scoped API keys