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
-
Download the Package:
- Download the latest version of the kwikpaisa-php-packages.zip file from the KwikPaisa website or repository.
-
Extract the Package:
- Unzip the kwikpaisa-php-packages.zip file to extract the SDK and its dependencies.
-
Include the SDK in Your Project:
- Copy the extracted
kwikpaisa
folder into your project’s directory. For example, place it in thepackages
folder.
- Copy the extracted
-
Autoload the SDK:
- Update your
composer.json
file to include the following autoload configuration:
"autoload": { "psr-4": { "Jangras\\Kwikpaisa\\": "path/to/kwikpaisa/src/" } }
- Replace
"path/to/kwikpaisa/src/"
with the actual path where you copied thekwikpaisa
folder.
- Update your
-
Update Composer Autoload:
- Run the following command to regenerate the Composer autoload files:
composer dump-autoload
-
Clear Laravel's Configuration and Cache:
- Run these Artisan commands to ensure Laravel picks up the new changes:
php artisan config:clear php artisan cache:clear
-
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
-
Require the SDK:
- Execute the following Composer command to install the KwikPaisa SDK:
composer require jangras/kwikpaisa
-
Composer Installation:
- Composer will automatically download and install the SDK and its dependencies.
-
Autoloading:
- Composer will handle autoloading of SDK classes, so no additional autoload configuration is necessary.
-
Clear Laravel's Configuration and Cache:
- Run these Artisan commands to ensure Laravel picks up the new changes:
php artisan config:clear php artisan cache:clear
-
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
.env
FileAdd the following KwikPaisa configuration parameters to your .env
file:
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
config/kwikpaisa.php
Create a configuration file for KwikPaisa in the config
directory:
-
Create
config/kwikpaisa.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'), ];
-
Register the Service Provider:
- If using a custom service provider, add it to the
providers
array inconfig/app.php
:
'providers' => [ // Other Service Providers Jangras\Kwikpaisa\KwikPaisaServiceProvider::class, ],
- If using a custom service provider, add it to the
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.
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:
$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:
$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
:
$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:
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
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
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);
}
}
}