Kipay Payment Gateway

API Reference

The Kipay Payment Gateway provides a comprehensive API for integrating payment processing into your applications.

Authentication: All API requests require an API key for authentication. You can get your API key from the Dashboard Settings.

Authentication

All API requests must include your API key in the X-API-Key header:

curl -X POST \
  https://kipay.benfex.net/api/transactions/initialize \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key_here' \
  -d '{
    "amount": 10000,
    "email": "[email protected]",
    "payment_channel_id": 1
  }'

Endpoints

Transactions

POST /api/transactions/initialize

Initialize a new transaction and get a payment URL

Request Body
{
  "amount": 10000,
  "email": "[email protected]",
  "payment_channel_id": 1,
  "description": "Payment for Order #12345",
  "currency": "KSH",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+2547012345678"
}
Response
{
  "status": "success",
  "message": "Success",
  "transaction": {
    "id": 1,
    "reference": "KIPAY12345678",
    "amount": 10000,
    "status": "pending",
    "created_at": "2025-04-10T12:34:56.000Z"
  },
  "authorization_url": "https://kipay.benfex.net/payment/checkout/KIPAY12345678",
  "access_code": "ACCESS_CODE",
  "reference": "KIPAY12345678"
}

GET /api/transactions/verify/{reference}

Verify a transaction's status

Parameters
  • reference - Transaction reference
Response
{
  "status": "success",
  "transaction": {
    "id": 1,
    "reference": "KIPAY12345678",
    "amount": 10000,
    "status": "completed",
    "payment_method": "card",
    "created_at": "2025-04-10T12:34:56.000Z"
  },
  "status": "completed"
}

GET /api/transactions/list

List all transactions

Query Parameters
  • page - Page number (default: 1)
  • limit - Items per page (default: 20)
  • status - Filter by status (pending, completed, failed)
  • date_from - Filter by start date (YYYY-MM-DD)
  • date_to - Filter by end date (YYYY-MM-DD)
Response
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "reference": "KIPAY12345678",
      "amount": 10000,
      "status": "completed",
      "created_at": "2025-04-10T12:34:56.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "pages": 1
}

Payment Channels

POST /api/payment-channels/create

Create a new payment channel

Request Body
{
  "name": "My Paystack Channel",
  "provider": "paystack",
  "config": {
    "public_key": "pk_test_xxxxxxxxxxxxxxxxxxxxxxxx",
    "secret_key": "sk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}
Response
{
  "status": "success",
  "message": "Payment channel created successfully",
  "channel": {
    "id": 1,
    "name": "My Paystack Channel",
    "provider": "paystack",
    "is_active": true,
    "is_default": true,
    "created_at": "2025-04-10T12:34:56.000Z"
  }
}

M-Pesa Specific Endpoints

POST /api/mpesa/stk-push

Initiate M-Pesa STK Push payment

Request Body
{
  "amount": 1000,
  "phone_number": "254712345678",
  "payment_channel_id": 7,
  "reference": "ORDER123",
  "description": "Payment for Services"
}
Response
{
  "status": "success",
  "message": "STK Push initiated",
  "transaction": {
    "id": 1,
    "reference": "MPESA12345678",
    "amount": 1000,
    "phone_number": "254712345678",
    "status": "pending",
    "checkout_request_id": "ws_CO_date_transaction_id",
    "created_at": "2025-04-10T12:34:56.000Z"
  }
}

GET /api/mpesa/stk-status/{reference}

Check the status of an M-Pesa STK Push transaction

Parameters
  • reference - Transaction reference
Response
{
  "status": "success",
  "transaction": {
    "id": 1,
    "reference": "MPESA12345678",
    "amount": 1000,
    "phone_number": "254712345678",
    "status": "completed",
    "payment_method": "mpesa_stk",
    "created_at": "2025-04-10T12:34:56.000Z"
  }
}

POST /api/mpesa/register-c2b-urls

Register Confirmation and Validation URLs for C2B transactions

Request Body
{
  "payment_channel_id": 7,
  "confirmation_url": "https://kipay.benfex.net/mpesa/confirmation",
  "validation_url": "https://kipay.benfex.net/mpesa/validation"
}
Response
{
  "status": "success",
  "message": "C2B URLs registered successfully",
  "urls": {
    "confirmation": "https://kipay.benfex.net/mpesa/confirmation",
    "validation": "https://kipay.benfex.net/mpesa/validation"
  }
}

POST /api/mpesa/simulate-c2b

Simulate a Customer-to-Business (C2B) transaction (Sandbox only)

Request Body
{
  "payment_channel_id": 7,
  "amount": 1000,
  "phone_number": "254712345678",
  "reference": "TEST_TRANSACTION"
}
Response
{
  "status": "success",
  "message": "C2B transaction simulated",
  "transaction": {
    "amount": 1000,
    "phone_number": "254712345678",
    "reference": "TEST_TRANSACTION",
    "status": "completed"
  }
}
M-Pesa API Notes:
  • STK Push and C2B simulations are only available in sandbox mode
  • Ensure phone numbers are in the format 254XXXXXXXXX
  • Keep your API credentials secure
  • Register your webhook URLs before using C2B transactions

GET /api/payment-channels/list

List all payment channels

Query Parameters
  • active_only - Filter to active channels only (default: false)
Response
{
  "status": "success",
  "channels": [
    {
      "id": 1,
      "name": "My Paystack Channel",
      "provider": "paystack",
      "is_active": true,
      "is_default": true,
      "created_at": "2025-04-10T12:34:56.000Z"
    }
  ]
}

Customers

POST /api/customers/create

Create a new customer

Request Body
{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+2547012345678"
}
Response
{
  "status": "success",
  "message": "Customer created successfully",
  "customer": {
    "id": 1,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+2547012345678",
    "created_at": "2025-04-10T12:34:56.000Z"
  }
}

GET /api/customers/list

List all customers

Query Parameters
  • page - Page number (default: 1)
  • limit - Items per page (default: 20)
  • search - Search by name, email, or phone
Response
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+2547012345678",
      "created_at": "2025-04-10T12:34:56.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "pages": 1
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response will include an error message:

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

Rate Limiting

API requests are rate limited to 100 requests per minute per API key. If you exceed this limit, you will receive a 429 Too Many Requests response.