Takalo API Documentation

Official API documentation for Takalo services

MVola Payment API

Overview

The MVola Payment API automatically processes MVola mobile money payments for Takalo’s cryptocurrency exchange. When customers send MVola payments, this API captures transaction data in real-time and makes it available for automated crypto payouts.

Base URL: https://mvola.takalo.xyz

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer mvola-webhook-2025-takalo

Endpoints

1. Get Recent Transactions

GET /transactions

Returns a list of recent MVola transactions.

Response:

{
  "total": 5,
  "recent": [
    {
      "id": 2,
      "created_at": "2025-07-07T07:45:50.810713+00:00",
      "amount": 1800000,
      "reference": "BLUE47",
      "sender": "+261341234567",
      "type": "sms",
      "timestamp": 1751874349,
      "balance": 15800000,
      "raw_sms": "Vous avez reçu 1,800,000 MGA de +261341234567. Ref: BLUE47. Nouveau solde: 15,800,000 MGA"
    }
  ]
}

Query Parameters:

Example:

curl https://mvola.takalo.xyz/transactions?limit=5 \
  -H "Authorization: Bearer mvola-webhook-2025-takalo"

2. Get Transaction by Reference

GET /transactions/{reference}

Retrieve a specific transaction by its reference code.

Example:

curl https://mvola.takalo.xyz/transactions/BLUE47 \
  -H "Authorization: Bearer mvola-webhook-2025-takalo"

Response:

{
  "id": 2,
  "amount": 1800000,
  "reference": "BLUE47",
  "sender": "+261341234567",
  "type": "sms",
  "timestamp": 1751874349,
  "balance": 15800000,
  "raw_sms": "Vous avez reçu 1,800,000 MGA de +261341234567. Ref: BLUE47. Nouveau solde: 15,800,000 MGA",
  "created_at": "2025-07-07T07:45:50.810713+00:00"
}

3. Get Latest Transaction + Stats

GET /latest

Returns the most recent transaction along with system statistics.

Response:

{
  "status": "healthy",
  "server_time": "2025-07-07T08:30:00.000Z",
  "uptime_seconds": 86400,
  "total_transactions": 25,
  "last_transaction": {
    "id": 2,
    "amount": 1800000,
    "reference": "BLUE47",
    "sender": "+261341234567",
    "created_at": "2025-07-07T07:45:50.810713+00:00"
  },
  "database_connected": true
}

4. Health Check

GET /health

Simple health check endpoint for monitoring.

Response:

{
  "status": "healthy",
  "server_time": "2025-07-07T08:30:00.000Z",
  "uptime_seconds": 86400,
  "database_connected": true
}

5. Update Transaction Status

PUT /transactions/{reference}

Update the status of a transaction (e.g., mark as paid).

Request Body:

{
  "status": "completed",
  "crypto_txid": "0x1234567890abcdef",
  "notes": "USDT sent successfully"
}

Example:

curl -X PUT https://mvola.takalo.xyz/transactions/BLUE47 \
  -H "Authorization: Bearer mvola-webhook-2025-takalo" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "crypto_txid": "0x1234567890abcdef"
  }'

Data Fields

Transaction Object

Field Type Description
id integer Unique transaction ID
amount integer Amount in MGA (Malagasy Ariary)
reference string Customer reference code
sender string Phone number of sender
type string Payment type (always “sms”)
timestamp integer Unix timestamp from SMS
balance integer MVola account balance after transaction
raw_sms string Original SMS content
created_at string ISO timestamp when recorded
status string Transaction status (optional)
crypto_txid string Crypto transaction ID (optional)

Typical Integration Flow

  1. Customer requests crypto: User wants to buy 400 USDT
  2. Generate reference: Bot creates unique reference like “BLUE47”
  3. Instruct payment: “Send 1,800,000 MGA to 034-12-345-67 with ref BLUE47”
  4. Monitor for payment: Poll /transactions/BLUE47 or /latest
  5. Process crypto payout: When transaction appears, send USDT
  6. Update status: Mark transaction as completed with crypto txid

Example Integration Code

JavaScript/Node.js

const API_BASE = 'https://mvola.takalo.xyz';
const AUTH_TOKEN = 'mvola-webhook-2025-takalo';

// Check for specific payment
async function checkPayment(reference) {
  const response = await fetch(`${API_BASE}/transactions/${reference}`, {
    headers: {
      'Authorization': `Bearer ${AUTH_TOKEN}`
    }
  });
  
  if (response.status === 404) {
    return null; // Payment not found
  }
  
  return await response.json();
}

// Get recent payments
async function getRecentPayments() {
  const response = await fetch(`${API_BASE}/transactions?limit=10`, {
    headers: {
      'Authorization': `Bearer ${AUTH_TOKEN}`
    }
  });
  
  const data = await response.json();
  return data.recent;
}

// Mark payment as completed
async function markCompleted(reference, cryptoTxId) {
  await fetch(`${API_BASE}/transactions/${reference}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${AUTH_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'completed',
      crypto_txid: cryptoTxId
    })
  });
}

Python

import requests

API_BASE = 'https://mvola.takalo.xyz'
AUTH_TOKEN = 'mvola-webhook-2025-takalo'
headers = {'Authorization': f'Bearer {AUTH_TOKEN}'}

# Check for specific payment
def check_payment(reference):
    response = requests.get(f'{API_BASE}/transactions/{reference}', headers=headers)
    if response.status_code == 404:
        return None
    return response.json()

# Get recent payments
def get_recent_payments():
    response = requests.get(f'{API_BASE}/transactions?limit=10', headers=headers)
    return response.json()['recent']

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

404 Not Found

{
  "error": "Transaction not found"
}

500 Server Error

{
  "error": "Internal server error",
  "message": "Database connection failed"
}

Rate Limits

Support

For technical issues or questions about this API, contact the Takalo development team.

API Version: 1.0
Last Updated: July 2025