# Kilicow Payment Solution
API Integration Guide

Note: Please contact Kilicow Support to obtain your merchant credentials, test environment access, and API endpoint URLs.
Email: support@kilicow.com

## Overview

Kilicow Payment Solution enables secure, reliable payment processing in Pakistan with JazzCash and EasyPaisa. Integrate this gateway into your website or app in a few simple steps.

## Integration Steps

### 1. Account Setup

1. Contact our team at support@kilicow.com to register as a merchant.
2. Complete verification and get your unique Merchant Key plus documentation access.
3. Kilicow team will provide your merchant API endpoint and webhook URLs.

### 2. Payment Request

Send a POST request to the provided payment API endpoint with the following required parameters:

Parameter | Type | Required | Description
--- | --- | --- | ---
merchant_key | string | Yes | Your unique merchant identifier.
amount | float | Yes | Payment amount.
currency | string | Yes | Currency code (e.g. `pkr`).
txn_id | string | Yes | Your unique transaction/order ID.
pay_type | string | Yes | `jazzcash` or `easypaisa`

### Sample Request – PHP

    <?php
    $KILICOW_API_URL = "API_URL_FROM_SUPPORT";
    $MERCHANT_KEY = "YOUR_MERCHANT_KEY";
    $payment_data = [
      'merchant_key' => $MERCHANT_KEY,
      'amount' => 1500.00,
      'currency' => 'pkr',
      'txn_id' => 'ORDER_' . time(),
      'pay_type' => 'jazzcash' // or 'easypaisa'
    ];
    $ch = curl_init($KILICOW_API_URL);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payment_data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    curl_close($ch);
    $result = json_decode($response, true);
    ?>

### Sample Request – JavaScript (Fetch)

    const paymentData = {
      merchant_key: 'YOUR_MERCHANT_KEY',
      amount: 1500.00,
      currency: 'pkr',
      txn_id: 'ORDER_' + Date.now(),
      pay_type: 'jazzcash' // or 'easypaisa'
    };
    fetch('API_URL_FROM_SUPPORT', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams(paymentData)
    })
    .then(r => r.json()).then(data => {
      if (data.status === 'success') window.location = data.payment_url;
      else alert(data.message);
    });

### Response Examples

Success:

    {
      "status": "success",
      "message": "Payment initiated successfully",
      "transaction_id": "ORDER_1727514477",
      "payment_url": "https://secure.payment.url/pay"
    }

Error:

    {
      "status": "error",
      "message": "Error description"
    }

### 3. Webhook Integration

After payment completion, Kilicow will notify your webhook endpoint with POST data like:

    {
      "txn_id": "ORDER_1727514477",
      "status": "success",
      "amount": 1500.00,
      "order_sn": "ORDER_1727514477",
      "sign": "SIGNATURE"
    }

Always verify the sign parameter using your merchant key for security.

### Webhook Verification Example – PHP

    <?php
    function verifySignature($data, $merchant_key) {
      $sign = $data['sign'];
      unset($data['sign']);
      ksort($data);
      $str = '';
      foreach ($data as $k=>$v) $str .= "$k=$v&";
      $str .= "key=" . $merchant_key;
      return $sign === strtoupper(md5($str));
    }
    ?>

## Best Practices & Support

- Always keep API credentials secret and never expose them client-side.
- Use HTTPS for all API traffic.
- Log API events (success, errors) for future audit.
- Test all flows in the Kilicow sandbox before going live.
- Contact support for credentials, technical issues, or business queries.