PHP SDKs

Install the PHP server-side SDK to interact with KwikPaisa's APIs.

KwikPaisa PHP SDK Integration Guide

Overview

This guide provides instructions for integrating the KwikPaisa PHP SDK into your Laravel application. You can choose between downloading the SDK package or installing it via Composer. Additionally, the guide covers setting up the configuration files and using the SDK in your Laravel controllers.

Installation

Option 1: Download the Package File

1. Download the Package:

   • Download the latest version of the kwikpaisa-php-packages.zip file from the KwikPaisa website or repository.

2. Extract the Package:

   • Unzip the kwikpaisa-php-packages.zip file to extract the SDK and its dependencies.

3. Include the SDK in Your Project:

   • Copy the extracted kwikpaisa folder into your project’s directory. For example, place it in the packages folder.

4. Autoload the SDK:

   • Update your composer.json file to include the following autoload configuration:
   JSON

   "autoload": {
       "psr-4": {
           "Jangras\\Kwikpaisa\\": "path/to/kwikpaisa/src/"
       }
   }
   

   • Replace "path/to/kwikpaisa/src/" with the actual path where you copied the kwikpaisa folder.

5. Update Composer Autoload:

   • Run the following command to regenerate the Composer autoload files:
   Bash

   composer dump-autoload
   

6. Clear Laravel's Configuration and Cache:

   • Run these Artisan commands to ensure Laravel picks up the new changes:
   Bash

   php artisan config:clear
   php artisan cache:clear
   

7. Initialize and Use the SDK:

   • Initialize the SDK in your code as described in the SDK documentation and start using it.

Option 2: Install via Composer

1. Require the SDK:

   • Execute the following Composer command to install the KwikPaisa SDK:
   Bash

   composer require jangras/kwikpaisa
   

2. Composer Installation:

   • Composer will automatically download and install the SDK and its dependencies.

3. Autoloading:

   • Composer will handle autoloading of SDK classes, so no additional autoload configuration is necessary.

4. Clear Laravel's Configuration and Cache:

   • Run these Artisan commands to ensure Laravel picks up the new changes:
   Bash

   php artisan config:clear
   php artisan cache:clear
   

5. Initialize and Use the SDK:

   • After installation, initialize the SDK in your code as described in the SDK documentation and start using it.

Configuration

Step 1: Update .env File

Add the following KwikPaisa configuration parameters to your .env file:

env

KWIKPAISA_APP_ID=your_app_id
KWIKPAISA_SECRET_KEY=your_secret_key
KWIKPAISA_API_URL=https://uat.api.kwikpaisa.com
KWIKPAISA_ORDER_CURRENCY=INR

Replace your_app_id, your_secret_key, and the API URL with your actual KwikPaisa credentials.

Step 2: Configure config/kwikpaisa.php

Create a configuration file for KwikPaisa in the config directory:

1. Create config/kwikpaisa.php:

   PHP

   <?php
   
   return [
       'app_id' => env('KWIKPAISA_APP_ID'),
       'secret_key' => env('KWIKPAISA_SECRET_KEY'),
       'api_url' => env('KWIKPAISA_API_URL'),
       'order_currency' => env('KWIKPAISA_ORDER_CURRENCY'),
   ];
   

2. Register the Service Provider:

   • If using a custom service provider, add it to the providers array in config/app.php:
   PHP

   'providers' => [
       // Other Service Providers
   
       Jangras\Kwikpaisa\KwikPaisaServiceProvider::class,
   ],
   

Using KwikPaisa in Your Controller

To integrate KwikPaisa for order creation and handle responses in your Laravel application, follow these steps:

Step 1: Use the KwikPaisa Service

Ensure that the KwikPaisaService is imported into your controller. This service provides the necessary methods for interacting with the KwikPaisa API.

PHP

use Jangras\Kwikpaisa\KwikPaisaService;

Step 2: Sanitize Input Data

When receiving data from the request, it’s crucial to sanitize it to avoid potential security issues. Use PHP's filter_var function to sanitize each input:

PHP

$order_id = filter_var($request->input('order_id'), FILTER_SANITIZE_STRING);
$order_amount = filter_var($request->input('order_amount'), FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION);
$order_note = filter_var($request->input('order_note'), FILTER_SANITIZE_STRING);
$service_type = filter_var($request->input('service_type'), FILTER_SANITIZE_STRING);
$customer_name = filter_var($request->input('customer_name'), FILTER_SANITIZE_STRING);
$customer_email = filter_var($request->input('customer_email'), FILTER_SANITIZE_EMAIL);
$customer_phone = filter_var($request->input('customer_phone'), FILTER_SANITIZE_STRING);
$customer_address_line1 = filter_var($request->input('customer_address_line1'), FILTER_SANITIZE_STRING);
$customer_address_line2 = filter_var($request->input('customer_address_line2'), FILTER_SANITIZE_STRING);
$customer_address_city = filter_var($request->input('customer_address_city'), FILTER_SANITIZE_STRING);
$customer_address_state = filter_var($request->input('customer_address_state'), FILTER_SANITIZE_STRING);
$customer_address_country = filter_var($request->input('customer_address_country'), FILTER_SANITIZE_STRING);
$customer_address_postal_code = filter_var($request->input('customer_address_postal_code'), FILTER_SANITIZE_STRING);
$return_url = "http://127.0.0.1:8000/kwikpaisa-return-response?order_id=$order_id"; // Ensure this is a valid URL

Step 3: Prepare the Order Data

After sanitizing the input data, prepare the order data array that will be sent to the KwikPaisa API. This array includes all the necessary details for the order:

PHP

$orderData = [
    'order_id' => $order_id,
    'order_amount' => $order_amount,
    'order_currency' => config('kwikpaisa.order_currency'),
    'order_note' => $order_note,
    'service_type' => $service_type,
    'customer_name' => $customer_name,
    'customer_email' => $customer_email,
    'customer_phone' => $customer_phone,
    'customer_address_line1' => $customer_address_line1,
    'customer_address_line2' => $customer_address_line2,
    'customer_address_city' => $customer_address_city,
    'customer_address_state' => $customer_address_state,
    'customer_address_country' => $customer_address_country,
    'customer_address_postal_code' => $customer_address_postal_code,
    'return_url' => $return_url,
];

Step 4: Generate the Checksum

To ensure the integrity of the order data, generate a checksum using the generateChecksum method from the KwikPaisaService:

PHP

$orderData['order_checksum'] = $this->kwikPaisa->generateChecksum($orderData);

Step 5: Create the Order Using KwikPaisa SDK

Send the prepared order data to the KwikPaisa API to create the order. Handle the response to determine whether the order was successfully created or if there was an error:

PHP

try {
    $response = $this->kwikPaisa->createOrder($orderData);

    if ($response['code'] === '200') {
        // Redirect to the payment link
        return redirect($response['return_data']['payment_link']);
    } else {
        // Handle error and return specific JSON response
        $errorDescription = $response['return_data']['description'] ?? 'Unknown error';
        return response()->json(['error' => $errorDescription], 401);
    }
} catch (\Exception $e) {
    // Handle exception and return complete JSON response
    return response()->json([
        'error' => 'An error occurred while processing the order.',
        'details' => $e->getMessage()
    ], 500);
}

Example Controller for Handling Payment Gateway Order Creation

PHP

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Jangras\Kwikpaisa\KwikPaisaService;

class OrderController extends Controller
{
    protected $kwikPaisa;

    public function __construct(KwikPaisaService $kwikPaisa)
    {
        $this->kwikPaisa = $kwikPaisa;
    }

    public function createOrder(Request $request)
    {
        // Sanitize input data
        $order_id = filter_var($request->input('order_id'), FILTER_SANITIZE_STRING);
        $order_amount = filter_var($request->input('order_amount'), FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION);
        $order_note = filter_var($request->input('order_note'), FILTER_SANITIZE_STRING);
        $service_type = filter_var($request->input('service_type'), FILTER_SANITIZE_STRING);
        $customer_name = filter_var($request->input('customer_name'), FILTER_SANITIZE_STRING);
        $customer_email = filter_var($request->input('customer_email'), FILTER_SANITIZE_EMAIL);
        $customer_phone = filter_var($request->input('customer_phone'), FILTER_SANITIZE_STRING);
        $customer_address_line1 = filter_var($request->input('customer_address_line1'), FILTER_SANITIZE_STRING);
        $customer_address_line2 = filter_var($request->input('customer_address_line2'), FILTER_SANITIZE_STRING);
        $customer_address_city = filter_var($request->input('customer_address_city'), FILTER_SANITIZE_STRING);
        $customer_address_state = filter_var($request->input('customer_address_state'), FILTER_SANITIZE_STRING);
        $customer_address_country = filter_var($request->input('customer_address_country'), FILTER_SANITIZE_STRING);
        $customer_address_postal_code = filter_var($request->input('customer_address_postal_code'), FILTER_SANITIZE_STRING);
        $return_url = "http://127.0.0.1:8000/kwikpaisa-return-response?order_id=$order_id"; // This should be a valid and sanitized URL

        // Prepare the order data
        $orderData = [
            'order_id' => $order_id,
            'order_amount' => $order_amount,
            'order_currency' => config('kwikpaisa.order_currency'),
            'order_note' => $order_note,
            'service_type' => $service_type,
            'customer_name' => $customer_name,
            'customer_email' => $customer_email,
            'customer_phone' => $customer_phone,
            'customer_address_line1' => $customer_address_line1,
            'customer_address_line2' => $customer_address_line2,
            'customer_address_city' => $customer_address_city,
            'customer_address_state' => $customer_address_state,
            'customer_address_country' => $customer_address_country,
            'customer_address_postal_code' => $customer_address_postal_code,
            'return_url' => $return_url,
        ];

        // Generate checksum
        $orderData['order_checksum'] = $this->kwikPaisa->generateChecksum($orderData);

        try {
            // Create order using KwikPaisa SDK
            $response = $this->kwikPaisa->createOrder($orderData);

            // Check for success
            if ($response['code'] === '200') {
                // Redirect to the payment link
                return redirect($response['return_data']['payment_link']);
            } else {
                // Handle error and return specific JSON response
                $errorDescription = $response['return_data']['description'] ?? 'Unknown error';
                return response()->json(['error' => $errorDescription], 401);
            }
        } catch (\Exception $e) {
            // Handle exception and return complete JSON response
            return response()->json([
                'error' => 'An error occurred while processing the order.',
                'details' => $e->getMessage()
            ], 500);
        }
    }
}

---

Handling Return Responses

Once the payment is completed and KwikPaisa redirects back to your application, handle the return response to check the payment status.

Example Controller for Handling Return Responses

PHP

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Jangras\Kwikpaisa\KwikPaisaService;
use Illuminate\Support\Facades\Log;

class KwikPaisaController extends Controller
{
    protected $kwikPaisa;

    public function __construct(KwikPaisaService $kwikPaisa)
    {
        $this->kwikPaisa = $kwikPaisa;
    }

    public function handleReturnResponse(Request $request)
    {
        // Sanitize input data


        $order_id = filter_var($request->query('order_id'), FILTER_SANITIZE_STRING);

        // Prepare the order data
        $orderData = [
            'order_id' => $order_id,
        ];

        // Log the incoming request data
        Log::info('KwikPaisa Return Response Request:', $orderData);

        try {
            // Fetch order status using KwikPaisa SDK
            $response = $this->kwikPaisa->fetchStatus($orderData);

            // Log the API response
            Log::info('KwikPaisa Return Response:', $response);

            return response()->json($response);
        } catch (\Exception $e) {
            // Log the exception
            Log::error('Error fetching KwikPaisa order status:', ['exception' => $e->getMessage()]);

            // Handle exception and return complete JSON response
            return response()->json([
                'error' => 'An error occurred while fetching the order status.',
                'details' => $e->getMessage()
            ], 500);
        }
    }
}

---