K-Pay API Documentation

curl -X POST https://pay.esicia.com/ \
  -H "Content-Type: application/json" \
  -H "Kpay-Key: your_api_key" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)"

const axios = require('axios');

const apiKey = 'your_api_key';
const username = 'your_username';
const password = 'your_password';

const headers = {
    'Content-Type': 'application/json',
    'Kpay-Key': apiKey,
    'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64')
};

const client = axios.create({
    baseURL: 'https://pay.esicia.com',
    headers: headers
});

import java.net.http.*;
import java.util.Base64;

String apiKey = "your_api_key";
String username = "your_username";
String password = "your_password";

String auth = Base64.getEncoder().encodeToString(
    (username + ":" + password).getBytes()
);

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://pay.esicia.com/"))
    .header("Content-Type", "application/json")
    .header("Kpay-Key", apiKey)
    .header("Authorization", "Basic " + auth)
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

import 'dart:convert';
import 'package:http/http.dart' as http;

final String apiKey = 'your_api_key';
final String username = 'your_username';
final String password = 'your_password';

final String basicAuth = 'Basic ' + base64Encode(
    utf8.encode('$username:$password')
);

final headers = {
    'Content-Type': 'application/json',
    'Kpay-Key': apiKey,
    'Authorization': basicAuth,
};

final response = await http.post(
    Uri.parse('https://pay.esicia.com/'),
    headers: headers,
    body: jsonEncode(payload),
);

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

string apiKey = "your_api_key";
string username = "your_username";
string password = "your_password";

var client = new HttpClient();
client.BaseAddress = new Uri("https://pay.esicia.com/");

var byteArray = Encoding.ASCII.GetBytes($"{username}:{password}");
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));
client.DefaultRequestHeaders.Add("Kpay-Key", apiKey);
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

curl -X POST https://pay.esicia.com/ \
  -H "Content-Type: application/json" \
  -H "Kpay-Key: your_api_key" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "action": "pay",
    "msisdn": "250783300000",
    "email": "customer@example.com",
    "details": "Order #12345",
    "refid": "ORDER123456789",
    "amount": 5000,
    "currency": "RWF",
    "cname": "John Doe",
    "cnumber": "CUST001",
    "pmethod": "momo",
    "retailerid": "YOUR_RETAILER_ID",
    "returl": "https://yoursite.com/callback",
    "redirecturl": "https://yoursite.com/success"
  }'

const axios = require('axios');

const apiKey = 'your_api_key';
const username = 'your_username';
const password = 'your_password';

async function initiatePayment() {
    const payload = {
        action: 'pay',
        msisdn: '250783300000',
        email: 'customer@example.com',
        details: 'Order #12345',
        refid: 'ORDER' + Date.now(),
        amount: 5000,
        currency: 'RWF',
        cname: 'John Doe',
        cnumber: 'CUST001',
        pmethod: 'momo',
        retailerid: 'YOUR_RETAILER_ID',
        returl: 'https://yoursite.com/callback',
        redirecturl: 'https://yoursite.com/success'
    };

    try {
        const response = await axios.post('https://pay.esicia.com/', payload, {
            headers: {
                'Content-Type': 'application/json',
                'Kpay-Key': apiKey,
                'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64')
            }
        });

        if (response.data.success === 1) {
            console.log('Checkout URL:', response.data.url);
            // Redirect user to response.data.url
        } else {
            console.error('Error:', response.data.reply);
        }
    } catch (error) {
        console.error('Request failed:', error.message);
    }
}

initiatePayment();

import java.net.http.*;
import java.net.URI;
import java.util.Base64;
import org.json.*;

public class KPayPayment {
    private static final String API_KEY = "your_api_key";
    private static final String USERNAME = "your_username";
    private static final String PASSWORD = "your_password";
    
    public static void main(String[] args) throws Exception {
        JSONObject payload = new JSONObject();
        payload.put("action", "pay");
        payload.put("msisdn", "250783300000");
        payload.put("email", "customer@example.com");
        payload.put("details", "Order #12345");
        payload.put("refid", "ORDER" + System.currentTimeMillis());
        payload.put("amount", 5000);
        payload.put("currency", "RWF");
        payload.put("cname", "John Doe");
        payload.put("cnumber", "CUST001");
        payload.put("pmethod", "momo");
        payload.put("retailerid", "YOUR_RETAILER_ID");
        payload.put("returl", "https://yoursite.com/callback");
        payload.put("redirecturl", "https://yoursite.com/success");

        String auth = Base64.getEncoder().encodeToString(
            (USERNAME + ":" + PASSWORD).getBytes()
        );

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://pay.esicia.com/"))
            .header("Content-Type", "application/json")
            .header("Kpay-Key", API_KEY)
            .header("Authorization", "Basic " + auth)
            .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
            .build();

        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        JSONObject result = new JSONObject(response.body());
        if (result.getInt("success") == 1) {
            System.out.println("Checkout URL: " + result.getString("url"));
        } else {
            System.out.println("Error: " + result.getString("reply"));
        }
    }
}

import 'dart:convert';
import 'package:http/http.dart' as http;

class KPayService {
  final String apiKey = 'your_api_key';
  final String username = 'your_username';
  final String password = 'your_password';
  final String baseUrl = 'https://pay.esicia.com/';

  Future<Map<String, dynamic>> initiatePayment({
    required String phone,
    required String email,
    required String customerName,
    required int amount,
    required String refId,
  }) async {
    final String basicAuth = 'Basic ' + base64Encode(
      utf8.encode('$username:$password')
    );

    final payload = {
      'action': 'pay',
      'msisdn': phone,
      'email': email,
      'details': 'Payment for order',
      'refid': refId,
      'amount': amount,
      'currency': 'RWF',
      'cname': customerName,
      'cnumber': 'CUST001',
      'pmethod': 'momo',
      'retailerid': 'YOUR_RETAILER_ID',
      'returl': 'https://yoursite.com/callback',
      'redirecturl': 'https://yoursite.com/success',
    };

    final response = await http.post(
      Uri.parse(baseUrl),
      headers: {
        'Content-Type': 'application/json',
        'Kpay-Key': apiKey,
        'Authorization': basicAuth,
      },
      body: jsonEncode(payload),
    );

    final result = jsonDecode(response.body);
    
    if (result['success'] == 1) {
      // Navigate to WebView with result['url']
      return {'success': true, 'url': result['url']};
    } else {
      return {'success': false, 'error': result['reply']};
    }
  }
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class KPayService
{
    private readonly string _apiKey = "your_api_key";
    private readonly string _username = "your_username";
    private readonly string _password = "your_password";
    private readonly HttpClient _client;

    public KPayService()
    {
        _client = new HttpClient();
        _client.BaseAddress = new Uri("https://pay.esicia.com/");
        
        var byteArray = Encoding.ASCII.GetBytes($"{_username}:{_password}");
        _client.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));
        _client.DefaultRequestHeaders.Add("Kpay-Key", _apiKey);
    }

    public async Task<PaymentResponse> InitiatePaymentAsync(PaymentRequest request)
    {
        var payload = new
        {
            action = "pay",
            msisdn = request.Phone,
            email = request.Email,
            details = request.Description,
            refid = request.RefId,
            amount = request.Amount,
            currency = "RWF",
            cname = request.CustomerName,
            cnumber = "CUST001",
            pmethod = request.PaymentMethod,
            retailerid = "YOUR_RETAILER_ID",
            returl = "https://yoursite.com/callback",
            redirecturl = "https://yoursite.com/success"
        };

        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        
        var response = await _client.PostAsync("", content);
        var responseBody = await response.Content.ReadAsStringAsync();
        
        return JsonSerializer.Deserialize<PaymentResponse>(responseBody);
    }
}

public class PaymentRequest
{
    public string Phone { get; set; }
    public string Email { get; set; }
    public string CustomerName { get; set; }
    public string Description { get; set; }
    public string RefId { get; set; }
    public int Amount { get; set; }
    public string PaymentMethod { get; set; } = "momo";
}

curl -X POST https://pay.esicia.com/ \
  -H "Content-Type: application/json" \
  -H "Kpay-Key: your_api_key" \
  -H "Authorization: Basic $(echo -n 'username:password' | base64)" \
  -d '{
    "action": "checkstatus",
    "refid": "ORDER123456789"
  }'

async function checkPaymentStatus(refId) {
    const payload = {
        action: 'checkstatus',
        refid: refId
    };

    const response = await axios.post('https://pay.esicia.com/', payload, {
        headers: {
            'Content-Type': 'application/json',
            'Kpay-Key': apiKey,
            'Authorization': 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64')
        }
    });

    if (response.data.statusid === '01') {
        console.log('Payment successful!');
        console.log('MoMo Transaction:', response.data.momtransactionid);
    } else {
        console.log('Status:', response.data.statusdesc);
    }
    
    return response.data;
}

public JSONObject checkPaymentStatus(String refId) throws Exception {
    JSONObject payload = new JSONObject();
    payload.put("action", "checkstatus");
    payload.put("refid", refId);

    String auth = Base64.getEncoder().encodeToString(
        (USERNAME + ":" + PASSWORD).getBytes()
    );

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://pay.esicia.com/"))
        .header("Content-Type", "application/json")
        .header("Kpay-Key", API_KEY)
        .header("Authorization", "Basic " + auth)
        .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
        .build();

    HttpResponse<String> response = client.send(request, 
        HttpResponse.BodyHandlers.ofString());
    
    JSONObject result = new JSONObject(response.body());
    
    if ("01".equals(result.getString("statusid"))) {
        System.out.println("Payment successful!");
    }
    
    return result;
}

Future<Map<String, dynamic>> checkPaymentStatus(String refId) async {
    final String basicAuth = 'Basic ' + base64Encode(
      utf8.encode('$username:$password')
    );

    final payload = {
      'action': 'checkstatus',
      'refid': refId,
    };

    final response = await http.post(
      Uri.parse(baseUrl),
      headers: {
        'Content-Type': 'application/json',
        'Kpay-Key': apiKey,
        'Authorization': basicAuth,
      },
      body: jsonEncode(payload),
    );

    final result = jsonDecode(response.body);
    
    if (result['statusid'] == '01') {
      return {'success': true, 'data': result};
    } else {
      return {'success': false, 'status': result['statusdesc']};
    }
}

public async Task<StatusResponse> CheckPaymentStatusAsync(string refId)
{
    var payload = new
    {
        action = "checkstatus",
        refid = refId
    };

    var json = JsonSerializer.Serialize(payload);
    var content = new StringContent(json, Encoding.UTF8, "application/json");
    
    var response = await _client.PostAsync("", content);
    var responseBody = await response.Content.ReadAsStringAsync();
    
    var result = JsonSerializer.Deserialize<StatusResponse>(responseBody);
    
    if (result.StatusId == "01")
    {
        Console.WriteLine("Payment successful!");
    }
    
    return result;
}

// Express.js callback handler
const express = require('express');
const app = express();

app.use(express.json());

app.post('/callback', async (req, res) => {
    const { tid, refid, statusid, statusdesc, momtransactionid } = req.body;
    
    console.log('K-Pay Callback received:', req.body);
    
    try {
        if (statusid === '01') {
            // Payment successful
            // await Order.updateOne({ reference: refid }, { status: 'paid' });
            console.log('Payment successful for:', refid);
        } else {
            // Payment failed
            console.log('Payment failed for:', refid, statusdesc);
        }
        
        // IMPORTANT: Return required response
        res.json({
            tid: tid,
            refid: refid,
            reply: 'OK'
        });
    } catch (error) {
        console.error('Callback error:', error);
        res.status(500).json({ error: 'Processing failed' });
    }
});

app.listen(3000);

// Spring Boot Controller
@RestController
public class KPayCallbackController {
    
    @PostMapping("/callback")
    public ResponseEntity<Map<String, String>> handleCallback(
            @RequestBody KPayCallback callback) {
        
        String tid = callback.getTid();
        String refid = callback.getRefid();
        String statusid = callback.getStatusid();
        
        if ("01".equals(statusid)) {
            // Payment successful
            // orderService.updateOrderStatus(refid, "PAID");
            System.out.println("Payment successful for: " + refid);
        } else {
            // Payment failed
            System.out.println("Payment failed for: " + refid);
        }
        
        // Return required response
        Map<String, String> response = new HashMap<>();
        response.put("tid", tid);
        response.put("refid", refid);
        response.put("reply", "OK");
        
        return ResponseEntity.ok(response);
    }
}

// For Flutter mobile apps, handle callbacks on your backend.
// After redirect, verify payment status:

class PaymentVerificationService {
  Future<bool> verifyPayment(String refId) async {
    // After user returns from payment, verify the status
    final result = await kPayService.checkPaymentStatus(refId);
    
    if (result['success'] == true && 
        result['data']['statusid'] == '01') {
      // Payment confirmed
      await _updateLocalOrderStatus(refId, 'paid');
      return true;
    }
    return false;
  }
  
  Future<void> _updateLocalOrderStatus(String refId, String status) async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString('order_$refId', status);
  }
}

// ASP.NET Core Controller
[ApiController]
[Route("[controller]")]
public class CallbackController : ControllerBase
{
    [HttpPost]
    public IActionResult HandleCallback([FromBody] KPayCallback callback)
    {
        if (callback.StatusId == "01")
        {
            // Payment successful
            // _orderService.UpdateOrderStatus(callback.RefId, "Paid");
            Console.WriteLine($"Payment successful for: {callback.RefId}");
        }
        else
        {
            // Payment failed
            Console.WriteLine($"Payment failed for: {callback.RefId}");
        }

        // Return required response
        return Ok(new
        {
            tid = callback.Tid,
            refid = callback.RefId,
            reply = "OK"
        });
    }
}

public class KPayCallback
{
    public string Tid { get; set; }
    public string RefId { get; set; }
    public string MomTransactionId { get; set; }
    public string StatusId { get; set; }
    public string StatusDesc { get; set; }
}