Get Started

Welcome to the K-Pay API. This guide will help you integrate KPay into your application for seamless payments.

Authentication

API access is granted using Basic Authentication over HTTPS. You must also provide a list of whitelisted IPs from which your application will send requests.

# cURL Example
curl --user "your_username:your_password" https://pay.esicia.com/api/

Supported Payment Methods

The KPay API supports a variety of payment methods to cater to your customers' needs.

Payment Request

To initiate a payment, send a POST request with a JSON body to our endpoint. Below are the required and optional parameters.

Parameters

Request Body Example

{
    "msisdn": "0783300000",
    "details": "Order #123",
    "refid": "15947234071471114",
    "amount": 4200,
    "currency": "RWF",
    "email": "customer@example.com",
    "cname": "John Doe",
    "cnumber": "123456789",
    "pmethod": "momo",
    "retailerid": "02",
    "returl": "https://yourdomain.com/api/paymentack",
    "redirecturl": "https://yourdomain.com/payment-success",
    "bankid": "63510"
}

Successful Response (Pending)

{
    "reply": "PENDING",
    "url": "https://pay.esicia.com/checkout/A12343983489",
    "success": 1,
    "authkey": "m43snbf9oivnmersqh6mnllbh5",
    "tid": "E6974831594723691",
    "refid": "15947234071471114",
    "retcode": 0
}

Asynchronous Postback

Once a payment is completed, KPay will send an asynchronous POST request to the returl you provided. Your listener should expect the following data format and respond with a confirmation.

Successful Mobile Money Payment

{
    "tid": "A441489693051",
    "refid": "1489693046",
    "momtransactionid": "616730887",
    "payaccount": "0783300000",
    "statusid": "01",
    "statusdesc": "Successfully processed transaction."
}

Expected Response from Your Server

{
    "tid": "A441489693051",
    "refid": "1489693046",
    "reply": "OK"
}

Check Transaction Status

You can check the status of any transaction by sending a request with the transaction's tid or your refid. We recommend relying on this method over the postback for confirmation.

Request Body

{
    "tid": "A441489693051",
    "refid": "1489693046",
    "action": "checkstatus"
}

Response (Transaction Not Found)

{
    "tid": "",
    "refid": "",
    "momtransactionid": "",
    "statusid": "611",
    "statusdesc": "Transaction not found"
}

KPay Error Codes

These codes represent the status in the retcode (payment request) and statusid (postback) fields.

Bank & Institution Codes

Use these codes for the bankid parameter in your payment requests.

Test Cards

Use these card numbers for testing in the sandbox environment.