API Documentation â€” Katpay

Overview

Katpay provides a robust API for processing payments in Nigeria. Our API allows you to create virtual accounts, process transactions, and manage payouts securely.

PCI DSS Compliant

Bank-Level Security

Real-time Processing

Base URL

https://api.katpay.com/v1

Authentication

All API requests require authentication using your API keys. Keep your keys secure and never expose them in client-side code.

Required Headers

Header	Description	Required
`Authorization`	Bearer token with your API secret	Required
`api-key`	Your public API key	Required
`Content-Type`	Must be `application/json`	Required

JavaScript

const headers = {
  'Authorization': `Bearer ${apiSecret}`,
  'Content-Type': 'application/json',
  'api-key': apiKey
};

PHP

$headers = [
    'Authorization: Bearer ' . $apiSecret,
    'Content-Type: application/json',
    'api-key: ' . $apiKey
];

Python

headers = {
    'Authorization': f'Bearer {api_secret}',
    'Content-Type': 'application/json',
    'api-key': api_key
}

Quick Start

1

Get Your API Keys

Navigate to your dashboard and generate your API keys from the Developer section. You'll receive an apiKey and apiSecret.

2

Set Up Authentication

Include the required headers in all your API requests. Never expose your apiSecret in client-side code.

3

Create Your First Virtual Account

Use the Virtual Accounts API to create dynamic account numbers for your customers.

4

Handle Webhooks

Set up webhook endpoints to receive real-time notifications about transaction status.

Virtual Accounts

Create dynamic virtual accounts for your customers. These accounts are tied to your merchant account and allow you to receive payments.

POST

/virtual-accounts

Create a new virtual account for a customer

Request Body

Parameter	Type	Description	Required
`email`	string	Customer's email address	Required
`name`	string	Customer's full name	Required
`phoneNumber`	string	Customer's phone number	Required
`bankCode`	array	Array of bank codes (e.g., ["PALMPAY", "OPAY"])	Required
`merchantID`	string	Your merchant ID	Required

JavaScript

const axios = require('axios');

const apiKey = 'your-api-key';
const apiSecret = 'your-api-secret';

const headers = {
  'Authorization': `Bearer ${apiSecret}`,
  'Content-Type': 'application/json',
  'api-key': apiKey
};

const data = {
  email: 'customer@example.com',
  name: 'John Doe',
  phoneNumber: '+2348012345678',
  bankCode: ['PALMPAY'],
  merchantID: apiKey
};

axios.post('https://api.katpay.com/v1/virtual-accounts', data, { headers })
  .then(response => {
    console.log('Virtual account created:', response.data);
  })
  .catch(error => {
    console.error('Error:', error.response.data);
  });

PHP

$apiKey = 'your-api-key';
$apiSecret = 'your-api-secret';

$data = [
    'email' => 'customer@example.com',
    'name' => 'John Doe',
    'phoneNumber' => '+2348012345678',
    'bankCode' => ['PALMPAY'],
    'merchantID' => $apiKey
];

$headers = [
    'Authorization: Bearer ' . $apiSecret,
    'Content-Type: application/json',
    'api-key: ' . $apiKey
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.katpay.com/v1/virtual-accounts');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Python

import requests
import json

api_key = 'your-api-key'
api_secret = 'your-api-secret'

headers = {
    'Authorization': f'Bearer {api_secret}',
    'Content-Type': 'application/json',
    'api-key': api_key
}

data = {
    'email': 'customer@example.com',
    'name': 'John Doe',
    'phoneNumber': '+2348012345678',
    'bankCode': ['PALMPAY'],
    'merchantID': api_key
}

response = requests.post(
    'https://api.katpay.com/v1/virtual-accounts',
    headers=headers,
    data=json.dumps(data)
)

print(response.json())

Supported Banks

Bank Code	Bank Name	Status
`PALMPAY`	PalmPay	Active
`OPAY`	OPay	Active
`20897`	Other Bank	Active

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Katpay account. Set up webhook endpoints to automatically process payments, track transactions, and handle account updates.

Webhook Events

Event Type	Description
`virtual_account.payment_received`	Triggered when a payment is received into a virtual account
`transaction.completed`	Triggered when a transaction is successfully completed
`payout.processed`	Triggered when a payout has been processed

Required Headers

Header	Description
`X-Katpay-Signature`	HMAC SHA256 signature for webhook verification
`X-Katpay-Timestamp`	Unix timestamp when the webhook was sent

Webhook Handler Implementation

Implement webhook signature verification to ensure webhooks are authentic and from Katpay.

PHP

<?php
/**
 * KatPay Webhook Handler
 * Replace YOUR_SECRET_KEY with your Live Secret Key from KatPay
 */

// Your Live Secret Key from KatPay dashboard
$SECRET_KEY = 'your-webhook-secret-key';

// Get webhook data
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_KATPAY_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_KATPAY_TIMESTAMP'] ?? '';

header('Content-Type: application/json');

try {
    // Validate secret key is set
    if (empty($SECRET_KEY) || $SECRET_KEY === 'your-webhook-secret-key') {
        http_response_code(500);
        echo json_encode(['error' => 'Webhook secret not configured']);
        exit;
    }

    // Validate required headers
    if (empty($signature) || empty($timestamp)) {
        http_response_code(400);
        echo json_encode(['error' => 'Missing required headers']);
        exit;
    }

    // Verify signature
    $signedPayload = $timestamp . '.' . $payload;
    $expectedSignature = hash_hmac('sha256', $signedPayload, $SECRET_KEY);

    if (!hash_equals($expectedSignature, $signature)) {
        http_response_code(401);
        echo json_encode(['error' => 'Invalid signature']);
        exit;
    }

    // Process webhook
    $data = json_decode($payload, true);
    
    if (json_last_error() !== JSON_ERROR_NONE) {
        http_response_code(400);
        echo json_encode(['error' => 'Invalid JSON payload']);
        exit;
    }

    $eventType = $data['event_type'] ?? '';

    // Handle payment received event
    if ($eventType === 'virtual_account.payment_received') {
        $transaction = $data['data']['transaction'] ?? [];
        $amount = $transaction['order_amount'] ?? 0;
        $orderNo = $transaction['order_no'] ?? '';
        $transactionId = $transaction['id'] ?? '';
        
        // Your business logic here
        // Example: Update database, send confirmation email, etc.
        
        // Respond with success
        http_response_code(200);
        echo json_encode([
            'status' => 'success',
            'message' => 'Payment processed'
        ]);
    } else {
        // Handle other event types
        http_response_code(200);
        echo json_encode([
            'status' => 'success',
            'message' => 'Event received'
        ]);
    }

} catch (Exception $e) {
    http_response_code(500);
    echo json_encode(['error' => 'Internal server error']);
}
?>

Python (Flask)

from flask import Flask, request, jsonify
import hmac
import hashlib
import json

app = Flask(__name__)

# Your Live Secret Key from KatPay dashboard
SECRET_KEY = 'your-webhook-secret-key'

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    try:
        # Get webhook data
        payload = request.get_data(as_text=True)
        signature = request.headers.get('X-Katpay-Signature', '')
        timestamp = request.headers.get('X-Katpay-Timestamp', '')
        
        # Validate secret key
        if not SECRET_KEY or SECRET_KEY == 'your-webhook-secret-key':
            return jsonify({'error': 'Webhook secret not configured'}), 500
        
        # Validate required headers
        if not signature or not timestamp:
            return jsonify({'error': 'Missing required headers'}), 400
        
        # Verify signature
        signed_payload = f"{timestamp}.{payload}"
        expected_signature = hmac.new(
            SECRET_KEY.encode('utf-8'),
            signed_payload.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()
        
        if not hmac.compare_digest(expected_signature, signature):
            return jsonify({'error': 'Invalid signature'}), 401
        
        # Process webhook
        data = json.loads(payload)
        event_type = data.get('event_type', '')
        
        # Handle payment received event
        if event_type == 'virtual_account.payment_received':
            transaction = data.get('data', {}).get('transaction', {})
            amount = transaction.get('order_amount', 0)
            order_no = transaction.get('order_no', '')
            transaction_id = transaction.get('id', '')
            
            # Your business logic here
            # Example: Update database, send confirmation email, etc.
            
            return jsonify({
                'status': 'success',
                'message': 'Payment processed'
            }), 200
        
        # Handle other event types
        return jsonify({
            'status': 'success',
            'message': 'Event received'
        }), 200
        
    except Exception as e:
        return jsonify({'error': 'Internal server error'}), 500

if __name__ == '__main__':
    app.run(port=5000)

Node.js (Express)

const express = require('express');
const crypto = require('crypto');

const app = express();

// Your Live Secret Key from KatPay dashboard
const SECRET_KEY = 'your-webhook-secret-key';

// Middleware to get raw body for signature verification
app.use(express.json({
    verify: (req, res, buf) => {
        req.rawBody = buf.toString('utf8');
    }
}));

app.post('/webhook', (req, res) => {
    try {
        // Get webhook data
        const payload = req.rawBody;
        const signature = req.headers['x-katpay-signature'] || '';
        const timestamp = req.headers['x-katpay-timestamp'] || '';
        
        // Validate secret key
        if (!SECRET_KEY || SECRET_KEY === 'your-webhook-secret-key') {
            return res.status(500).json({ error: 'Webhook secret not configured' });
        }
        
        // Validate required headers
        if (!signature || !timestamp) {
            return res.status(400).json({ error: 'Missing required headers' });
        }
        
        // Verify signature
        const signedPayload = `${timestamp}.${payload}`;
        const expectedSignature = crypto
            .createHmac('sha256', SECRET_KEY)
            .update(signedPayload)
            .digest('hex');
        
        if (expectedSignature !== signature) {
            return res.status(401).json({ error: 'Invalid signature' });
        }
        
        // Process webhook
        const data = req.body;
        const eventType = data.event_type || '';
        
        // Handle payment received event
        if (eventType === 'virtual_account.payment_received') {
            const transaction = data.data?.transaction || {};
            const amount = transaction.order_amount || 0;
            const orderNo = transaction.order_no || '';
            const transactionId = transaction.id || '';
            
            // Your business logic here
            // Example: Update database, send confirmation email, etc.
            
            return res.status(200).json({
                status: 'success',
                message: 'Payment processed'
            });
        }
        
        // Handle other event types
        return res.status(200).json({
            status: 'success',
            message: 'Event received'
        });
        
    } catch (error) {
        return res.status(500).json({ error: 'Internal server error' });
    }
});

app.listen(3000, () => {
    console.log('Webhook server running on port 3000');
});

Always verify webhook signatures

Validate timestamp to prevent replay attacks

Use HTTPS endpoints only

Security Best Practices

Protect Your API Keys

Never store API keys in your frontend code or public repositories.

Use HTTPS Only

Always use HTTPS for API requests to encrypt data in transit.

Monitor Webhooks

Implement webhook signature verification to ensure webhook authenticity.

Katpay API Documentation

Overview

Base URL

Authentication

Required Headers

Quick Start

Get Your API Keys

Set Up Authentication

Create Your First Virtual Account

Handle Webhooks

Virtual Accounts

Request Body

Supported Banks

Webhooks

Webhook Events

Required Headers

Webhook Handler Implementation

Security Best Practices

Protect Your API Keys

Use HTTPS Only

Monitor Webhooks