CollectUG API

curl -X POST https://collectug.com/api/merchant/callback-url \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-app.com/webhooks/collectug"
  }'

curl -X POST https://collectug.com/api/credit-account \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "phoneNumber": "0776913451",
    "merchant_reference": "ORDER-12345",
    "customer_email": "customer@example.com",
    "callback_url": "https://your-app.com/order/12345/callback"
  }'

curl -X POST https://collectug.com/api/credit-account \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "cardNumber": "4111111111111111",
    "cardholderName": "John Doe",
    "expiryDate": "12/25",
    "cvv": "123",
    "callback_url": "https://your-app.com/order/12345/callback"
  }'

curl -X POST https://collectug.com/api/debit-account \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "phoneNumber": "0776913451",
    "callback_url": "https://your-app.com/payouts/callback"
  }'

curl -X GET \
  "https://collectug.com/api/transactions?status=completed&start_date=2024-01-01&end_date=2024-01-31&page=1" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

{
  "transaction_id": "TXN_ABC123",
  "external_transaction_id": "EXT123456",
  "amount": 10000,
  "status": "completed",
  "currency": "UGX",
  "timestamp": "2024-01-15T10:30:00Z",
  "merchant_reference": "ORDER-12345",
  "customer_email": "customer@example.com",
  "service_provider": "mtn",
  "transaction_type": "deposit",
  "phone_number": "256776913451",
  "callback_source": "request",
  "signature": "hmac_sha256_signature_here"
}

<?php

class CollectUGClient {
    private $apiKey;
    private $baseUrl;

    public function __construct($apiKey, $baseUrl = 'https://collectug.com/api') {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }

    public function createDeposit($amount, $phoneNumber, $options = []) {
        $data = [
            'amount' => $amount,
            'phoneNumber' => $phoneNumber,
        ];

        if (isset($options['callback_url'])) {
            $data['callback_url'] = $options['callback_url'];
        }

        if (isset($options['merchant_reference'])) {
            $data['merchant_reference'] = $options['merchant_reference'];
        }

        return $this->request('/credit-account', $data);
    }

    public function createWithdrawal($amount, $phoneNumber, $callbackUrl = null) {
        $data = [
            'amount' => $amount,
            'phoneNumber' => $phoneNumber,
        ];

        if ($callbackUrl) {
            $data['callback_url'] = $callbackUrl;
        }

        return $this->request('/debit-account', $data);
    }

    public function getTransactions($filters = []) {
        return $this->request('/transactions', $filters, 'GET');
    }

    private function request($endpoint, $data = [], $method = 'POST') {
        $url = $this->baseUrl . $endpoint;

        $ch = curl_init($url);

        $headers = [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json',
            'Accept: application/json',
        ];

        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        } elseif ($method === 'GET' && !empty($data)) {
            $url .= '?' . http_build_query($data);
            curl_setopt($ch, CURLOPT_URL, $url);
        }

        $response = curl_exec($ch);
        $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return [
            'status' => $statusCode,
            'body' => json_decode($response, true)
        ];
    }
}

// Usage example
$client = new CollectUGClient('sk_live_your_api_key_here');

// Create a deposit
$result = $client->createDeposit(10000, '0776913451', [
    'merchant_reference' => 'ORDER-12345',
    'callback_url' => 'https://your-app.com/webhook'
]);

if ($result['status'] === 200) {
    echo "Transaction created: " . $result['body']['transaction']['transaction_id'];
} else {
    echo "Error: " . $result['body']['message'];
}

const axios = require('axios');

class CollectUGClient {
    constructor(apiKey, baseUrl = 'https://collectug.com/api') {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
        this.client = axios.create({
            baseURL: baseUrl,
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            }
        });
    }

    async createDeposit(amount, phoneNumber, options = {}) {
        const data = {
            amount,
            phoneNumber,
            ...options
        };

        try {
            const response = await this.client.post('/credit-account', data);
            return response.data;
        } catch (error) {
            throw new Error(error.response?.data?.message || error.message);
        }
    }

    async createWithdrawal(amount, phoneNumber, callbackUrl = null) {
        const data = {
            amount,
            phoneNumber
        };

        if (callbackUrl) {
            data.callback_url = callbackUrl;
        }

        try {
            const response = await this.client.post('/debit-account', data);
            return response.data;
        } catch (error) {
            throw new Error(error.response?.data?.message || error.message);
        }
    }

    async getTransactions(filters = {}) {
        try {
            const response = await this.client.get('/transactions', { params: filters });
            return response.data;
        } catch (error) {
            throw new Error(error.response?.data?.message || error.message);
        }
    }

    async verifyWebhookSignature(payload, signature, webhookSecret) {
        const crypto = require('crypto');

        // Remove signature from payload before hashing
        const { signature: _, ...dataToSign } = payload;

        const expectedSignature = crypto
            .createHmac('sha256', webhookSecret)
            .update(JSON.stringify(dataToSign))
            .digest('hex');

        return crypto.timingSafeEqual(
            Buffer.from(signature),
            Buffer.from(expectedSignature)
        );
    }
}

// Usage example
const client = new CollectUGClient('sk_live_your_api_key_here');

async function example() {
    try {
        // Create a deposit
        const deposit = await client.createDeposit(10000, '0776913451', {
            merchant_reference: 'ORDER-12345',
            callback_url: 'https://your-app.com/webhook'
        });

        console.log('Transaction created:', deposit.transaction.transaction_id);

        // Get transactions
        const transactions = await client.getTransactions({
            status: 'completed',
            start_date: '2024-01-01'
        });

        console.log('Total transactions:', transactions.summary.total);

    } catch (error) {
        console.error('Error:', error.message);
    }
}

example();

import requests
import json
import hmac
import hashlib

class CollectUGClient:
    def __init__(self, api_key, base_url='https://collectug.com/api'):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        })

    def create_deposit(self, amount, phone_number, **kwargs):
        """Create a deposit transaction"""
        data = {
            'amount': amount,
            'phoneNumber': phone_number
        }
        data.update(kwargs)

        response = self.session.post(f'{self.base_url}/credit-account', json=data)
        response.raise_for_status()
        return response.json()

    def create_withdrawal(self, amount, phone_number, callback_url=None):
        """Create a withdrawal transaction"""
        data = {
            'amount': amount,
            'phoneNumber': phone_number
        }

        if callback_url:
            data['callback_url'] = callback_url

        response = self.session.post(f'{self.base_url}/debit-account', json=data)
        response.raise_for_status()
        return response.json()

    def get_transactions(self, **filters):
        """Get transaction history with optional filters"""
        params = filters

        response = self.session.get(f'{self.base_url}/transactions', params=params)
        response.raise_for_status()
        return response.json()

    def verify_webhook_signature(self, payload, signature, webhook_secret):
        """Verify webhook signature"""
        # Remove signature from payload before hashing
        data_to_sign = payload.copy()
        data_to_sign.pop('signature', None)

        # Convert to JSON string
        message = json.dumps(data_to_sign, separators=(',', ':'), sort_keys=True)

        # Calculate expected signature
        expected_signature = hmac.new(
            webhook_secret.encode('utf-8'),
            msg=message.encode('utf-8'),
            digestmod=hashlib.sha256
        ).hexdigest()

        # Compare signatures
        return hmac.compare_digest(signature, expected_signature)

# Usage example
if __name__ == "__main__":
    client = CollectUGClient(api_key='sk_live_your_api_key_here')

    try:
        # Create a deposit
        deposit = client.create_deposit(
            amount=10000,
            phone_number='0776913451',
            merchant_reference='ORDER-12345',
            callback_url='https://your-app.com/webhook'
        )

        print(f"Transaction created: {deposit['transaction']['transaction_id']}")

        # Get recent transactions
        transactions = client.get_transactions(
            status='completed',
            start_date='2024-01-01'
        )

        print(f"Total transactions: {transactions['summary']['total']}")

    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        if e.response:
            print(f"Response: {e.response.json()}")