BLMPay API

Accept mobile money, card payments, and manage payouts programmatically. REST API with JSON request/response.

BASE URL

https://freelancer.blmtec.co.tz/api/v1

REST

JSON API

HTTPS

Secure only

Webhooks

Real-time events

Authentication

Include your API key as a Bearer token on every request:

HTTP HEADER

Authorization: Bearer YOUR_SECRET_KEY

⚠️ Keep your secret key safe

Never expose your secret key in frontend code or public repositories. Use it server-side only. If compromised, revoke it immediately from the dashboard.

→ Create a free account to get your API keys

Payments

POST /api/v1/payments Create a payment request

Send a USSD push to a mobile number, or generate a card checkout link.

Mobile Money Example

{
    "payment_type": "mobile",
    "details": {
        "amount": 5000,
        "currency": "TZS"
    },
    "phone_number": "255712345678",
    "customer": {
        "firstname": "Juma",
        "lastname": "Mwangi",
        "email": "juma@example.com"
    },
    "webhook_url": "https:\/\/yoursite.com\/webhooks",
    "metadata": {
        "order_id": "ORD-001"
    }
}

Card Payment Example

{
    "payment_type": "card",
    "details": {
        "amount": 50000,
        "currency": "TZS",
        "redirect_url": "https:\/\/yoursite.com\/success",
        "cancel_url": "https:\/\/yoursite.com\/cancel"
    },
    "customer": {
        "firstname": "Jane",
        "lastname": "Doe",
        "email": "jane@example.com",
        "country": "TZ"
    },
    "webhook_url": "https:\/\/yoursite.com\/webhooks",
    "metadata": {
        "order_id": "ORD-002"
    }
}
Field Type Required Description
payment_type string ✓ mobile or card
details.amount integer ✓ Amount in TZS (integers only)
details.currency string ✓ Must be TZS
phone_number string ✓ mobile Format: 255XXXXXXXXX (e.g. 255712345678)
details.redirect_url string ✓ card URL after successful card payment
details.cancel_url string ✓ card URL after cancelled card payment
customer.firstname string ✓ Customer first name
customer.lastname string ✓ Customer last name
customer.email string ✓ Customer email address
webhook_url string optional Your endpoint for payment events
metadata object optional Custom key-value pairs (must be {}, not [])
GET /api/v1/payments Supports ?limit=20&offset=0&status=completed
GET /api/v1/payments/{reference} Get single payment by reference e.g. BP240101ABCD1234

Invoices

POST /api/v1/invoices 
{
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "255787654321",
    "items": [
        {
            "name": "Web Design",
            "quantity": 1,
            "unit_price": 200000
        }
    ],
    "tax_percent": 18,
    "due_date": "2026-08-01",
    "notes": "Payment due within 30 days"
}

Balance

GET /api/v1/balance 
{
    "status": "success",
    "code": 200,
    "data": {
        "available": {
            "currency": "TZS",
            "value": 329194
        },
        "total": {
            "currency": "TZS",
            "value": 329194
        },
        "pending": {
            "currency": "TZS",
            "value": 5000
        }
    }
}

Webhook Events

We send HTTP POST requests to your webhook URL for these events. Verify the signature before processing.

Event Description
payment.completed Payment successfully received
payment.failed Payment failed or declined
payment.voided Payment voided/cancelled
payment.expired Payment link expired (4 hours)
payment.cancelled Payment cancelled by customer
payout.completed Payout sent to recipient
payout.failed Payout failed — funds returned

Verify webhook signatures

Every request includes X-Webhook-Signature (HMAC-SHA256). Always verify before processing.

$sig = hash_hmac("sha256", $timestamp . "." . $rawBody, $webhookSecret);
if (!hash_equals($sig, $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"])) {
    http_response_code(401); exit("Invalid signature");
}

Error Codes

HTTP Error Code Meaning
401 unauthorized Missing or invalid API key
403 insufficient_scope API key lacks required scope
400 validation_error Invalid request parameters
404 not_found Resource not found
429 rate_limit_exceeded Too many requests (60/min)
500 payment_failed Payment gateway error

SDKs & Quick Start

Get started with a simple cURL example:

CURL — Mobile Payment

curl -X POST https://freelancer.blmtec.co.tz/api/v1/payments \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_type": "mobile",
    "details": {"amount": 5000, "currency": "TZS"},
    "phone_number": "255712345678",
    "customer": {"firstname": "Juma", "lastname": "Mwangi", "email": "juma@example.com"},
    "webhook_url": "https://yoursite.com/webhooks",
    "metadata": {}
  }'