Developer Documentation

Integrate Franzik Pay into your application with our simple and secure API

Quick Start

Get your API key from your Franzik Pay dashboard. All API requests require authentication via API key.
Demo API Key: apk_demo_1234567890abcdef

STK Push Payment

Initiate an M-Pesa STK Push payment to a customer's phone. The customer will receive a prompt to enter their PIN and complete the payment.

POST https://franzik.co.ke/api/stkpush

Request Parameters

ParameterTypeRequiredDescription
api_keystringRequiredYour API key from Franzik Pay
phonestringRequiredCustomer's M-Pesa phone number (format: 2547XXXXXXXX)
amountintegerRequiredAmount to charge in KES (minimum 1)
invoicestringRequiredUnique invoice/reference number for the transaction
emailstringRequiredCustomer or merchant email address

Example Request

async function initiateSTKPush() {
    const response = await fetch('https://franzik.co.ke/api/stkpush', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            api_key: 'apk_demo_1234567890abcdef',
            phone: '254712345678',
            amount: 100,
            invoice: 'INV-001',
            email: '[email protected]'
        })
    });
    
    const data = await response.json();
    console.log(data);
}
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => 'https://franzik.co.ke/api/stkpush',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'api_key' => 'apk_demo_1234567890abcdef',
        'phone' => '254712345678',
        'amount' => 100,
        'invoice' => 'INV-001',
        'email' => '[email protected]'
    ]),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json']
]);

$response = curl_exec($curl);
$data = json_decode($response, true);
print_r($data);
import requests
import json

url = "https://franzik.co.ke/api/stkpush"
payload = {
    "api_key": "apk_demo_1234567890abcdef",
    "phone": "254712345678",
    "amount": 100,
    "invoice": "INV-001",
    "email": "[email protected]"
}

response = requests.post(url, json=payload)
print(response.json())
curl -X POST https://franzik.co.ke/api/stkpush \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "apk_demo_1234567890abcdef",
    "phone": "254712345678",
    "amount": 100,
    "invoice": "INV-001",
    "email": "[email protected]"
  }'

Success Response

{
  "status": 1,
  "message": "STK Push sent successfully",
  "checkout_id": "FRA_20240415_123456_a1b2c3d4"
}

Error Responses

{
  "status": 0,
  "message": "Invalid API key"
}

{
  "status": 3,
  "message": "Token limit reached"
}

{
  "status": 0,
  "message": "STK Push failed"
}

Query Transaction Status

Check the status of a transaction using the system_checkout_id returned from the STK Push request.

POST https://franzik.co.ke/api/query

Request Parameters

ParameterTypeRequiredDescription
api_keystringRequiredYour API key from Franzik Pay
system_checkout_idstringRequiredThe checkout ID returned from STK Push request

Example Request

async function queryTransaction(checkoutId) {
    const response = await fetch('https://franzik.co.ke/api/query', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            api_key: 'apk_demo_1234567890abcdef',
            system_checkout_id: checkoutId
        })
    });
    
    const data = await response.json();
    if (data.transaction_status === 'SUCCESS') {
        console.log(`Payment of KES ${data.amount} completed!`);
    }
    return data;
}
function queryTransaction($checkoutId) {
    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => 'https://franzik.co.ke/api/query',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode([
            'api_key' => 'apk_demo_1234567890abcdef',
            'system_checkout_id' => $checkoutId
        ]),
        CURLOPT_HTTPHEADER => ['Content-Type: application/json']
    ]);
    
    $response = curl_exec($curl);
    return json_decode($response, true);
}
def query_transaction(checkout_id):
    url = "https://franzik.co.ke/api/query"
    payload = {
        "api_key": "apk_demo_1234567890abcdef",
        "system_checkout_id": checkout_id
    }
    
    response = requests.post(url, json=payload)
    return response.json()
curl -X POST https://franzik.co.ke/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "apk_demo_1234567890abcdef",
    "system_checkout_id": "FRA_20240415_123456_a1b2c3d4"
  }'

Success Response

{
  "status": 1,
  "transaction_status": "SUCCESS",
  "message": "Payment completed successfully",
  "amount": 100.00,
  "invoice": "INV-001",
  "safaricom_response": {
    "ResultCode": "0",
    "ResultDesc": "The service request is processed successfully."
  }
}

Transaction Status Values

SUCCESS - Payment completed successfully

PENDING - Waiting for customer action

FAILED - Payment failed (insufficient funds, timeout, etc.)

CANCELLED - Cancelled by user

Error Response

{
  "status": 0,
  "message": "Transaction not found"
}

Webhooks

Receive real-time payment notifications when transaction status changes. Configure your callback URL in the dashboard.

POST Your Callback URL
Your server must respond with HTTP 200 status within 10 seconds. We'll retry failed webhooks up to 3 times.

Webhook Payload

{
  "system_checkout_id": "FRA_20240415_123456_a1b2c3d4",
  "transaction_status": "SUCCESS",
  "amount": 100.00,
  "invoice": "INV-001",
  "phone": "254712345678",
  "mpesa_receipt": "RGF84J3K2L",
  "transaction_date": "2024-04-15 14:30:25"
}

Example Webhook Handler (PHP)

$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

if ($data['transaction_status'] === 'SUCCESS') {
    // Update order status in your database
    // Send confirmation email
    // Fulfill order
    updateOrderStatus($data['invoice'], 'completed');
}

// Always respond with 200 OK
http_response_code(200);
echo 'OK';

Error Codes Reference

Status CodeMessageDescription
0Invalid API keyThe API key provided is not recognized
0API key inactiveThe API key exists but is inactive
3Token limit reachedYour plan's transaction limit has been reached
0Invalid inputMissing or invalid parameters
0Transaction not foundThe checkout ID does not exist
0STK Push failedCould not initiate M-Pesa payment

Need Help?

Email: [email protected]
Phone: +254 757 237 042
Support Hours: Monday-Friday, 8:00 AM - 6:00 PM