Esewa SDK for PHP

https://github.com/xentixar/esewa-sdk
Admin
This PHP SDK provides a simple interface to integrate Esewa payment gateway functionality, allowing...
Tokens:4,664
Snippets:25
Trust Score:7.3
License:MIT
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Esewa SDK using Composer

Source: https://github.com/xentixar/esewa-sdk/blob/main/README.md

Installs the Esewa SDK for PHP using Composer. This is the primary method for including the SDK in your project.

```bash
composer require xentixar/esewa-sdk
```

--------------------------------

### PHP: Complete Esewa Payment Flow Integration

Source: https://context7.com/xentixar/esewa-sdk/llms.txt

This PHP code snippet illustrates the end-to-end integration of the Esewa payment gateway. It covers initiating a payment, processing the success callback with server-side validation, and handling payment failures. Dependencies include the Esewa SDK (installed via Composer) and session management. Input is via POST for initiation and GET for callbacks. Output includes redirection to payment, success, or failure pages.

```php
<?php

require_once 'vendor/autoload.php';

use Xentixar\EsewaSdk\Esewa;

// === STEP 1: Initiate Payment (on checkout page) ===

session_start();

if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_POST['proceed_payment'])) {

    $orderId = 'ORD-' . time() . '-' . rand(10000, 99999);
    $orderAmount = 5000.00;
    $taxAmount = 650.00;

    // Store order details in session or database
    $_SESSION['pending_order'] = [
        'order_id' => $orderId,
        'amount' => $orderAmount,
        'tax' => $taxAmount,
        'total' => $orderAmount + $taxAmount
    ];

    $esewa = new Esewa();

    // Use production credentials for live environment
    $isProduction = false; // Set to true in production
    $secretKey = $isProduction ? 'your_production_secret_key' : '8gBm/:&EnhH.1/q';
    $productCode = $isProduction ? 'YOUR_PRODUCT_CODE' : 'EPAYTEST';

    $esewa->config(
        'https://yourwebsite.com/esewa/success',
        'https://yourwebsite.com/esewa/failure',
        $orderAmount,
        $orderId,
        $productCode,
        $secretKey,
        $taxAmount,
        0,  // service charge
        0   // delivery charge
    );

    // This redirects user to Esewa payment page
    $esewa->init($isProduction);
    exit;
}

// === STEP 2: Handle Success Callback ===

// File: esewa/success.php
if (isset($_GET['data'])) {

    $esewa = new Esewa();
    $responseData = $esewa->decode();

    if (!$responseData) {
        header('Location: /payment/error?msg=invalid_response');
        exit;
    }

    $transactionUuid = $responseData['transaction_uuid'];
    $totalAmount = $responseData['total_amount'];
    $status = $responseData['status'];
    $productCode = $responseData['product_code'] ?? 'EPAYTEST';

    // Verify the transaction with Esewa's server
    $isProduction = false;
    $validationResponse = $esewa->validate(
        $totalAmount,
        $transactionUuid,
        $isProduction,
        $productCode
    );

    $validationData = json_decode($validationResponse, true);

    if ($validationData &&
        $validationData['status'] === 'COMPLETE' &&
        $validationData['transaction_uuid'] === $transactionUuid) {

        // Payment verified successfully
        $refId = $validationData['ref_id'];
        $transactionCode = $validationData['transaction_code'];

        // Update database
        // $db->query("UPDATE orders SET status='paid', payment_ref='$refId',
        //             transaction_code='$transactionCode' WHERE order_id='$transactionUuid'");

        // Clear pending order from session
        unset($_SESSION['pending_order']);

        // Redirect to success page
        header("Location: /order/confirmation?order_id=$transactionUuid&ref=$refId");
        exit;

    } else {
        // Validation failed - possible fraud attempt
        error_log("Esewa validation mismatch: " . json_encode($validationData));
        header('Location: /payment/error?msg=validation_failed');
        exit;
    }
}

// === STEP 3: Handle Failure Callback ===

// File: esewa/failure.php
session_start();

if (isset($_SESSION['pending_order'])) {
    $orderId = $_SESSION['pending_order']['order_id'];

    // Log the failed transaction
    error_log("Payment failed for order: $orderId");

    // Update order status in database
    // $db->query("UPDATE orders SET status='payment_failed' WHERE order_id='$orderId'");

    // Redirect to cart or checkout with error message
    header('Location: /checkout?error=payment_cancelled');
    exit;
} else {
    header('Location: /');
    exit;
}

```

--------------------------------

### Generate Autoloader with Composer

Source: https://github.com/xentixar/esewa-sdk/blob/main/README.md

Generates the Composer autoloader after installing or updating dependencies. This allows for easy class loading.

```bash
composer dump-autoload
```

--------------------------------

### Decode Esewa Payment Response in PHP

Source: https://github.com/xentixar/esewa-sdk/blob/main/README.md

Decodes the response received from Esewa after a payment process. It checks for the 'data' parameter in the GET request.

```php
$responseData = $esewa->decode();
```

--------------------------------

### Decode Esewa Payment Response (PHP)

Source: https://context7.com/xentixar/esewa-sdk/llms.txt

Processes a base64-encoded payment response from Esewa using the `decode()` method. It extracts transaction details, such as transaction code, status, and amount, from GET parameters. This method is essential for verifying the initial payment status on the success URL endpoint.

```php
<?php

require_once 'vendor/autoload.php';

use Xentixar\EsewaSdk\Esewa;

// This code runs on your success_url endpoint
// Example: https://yourwebsite.com/payment/verify?data=eyJ0cmFuc2FjdGlvbl9jb2RlIjoi...

$esewa = new Esewa();

try {
    $responseData = $esewa->decode();

    if ($responseData) {
        // Successfully decoded response
        // Sample decoded data structure:
        // [
        //     'transaction_code' => '0007Y5T',
        //     'status' => 'COMPLETE',
        //     'total_amount' => '2000.0',
        //     'transaction_uuid' => 'ORDER-1234567890-5678',
        //     'product_code' => 'EPAYTEST',
        //     'signed_field_names' => 'transaction_code,status,total_amount,transaction_uuid,product_code,signed_field_names',
        //     'signature' => 'base64_signature_string'
        // ]

        $transactionCode = $responseData['transaction_code'] ?? null;
        $status = $responseData['status'] ?? null;
        $totalAmount = $responseData['total_amount'] ?? null;
        $transactionUuid = $responseData['transaction_uuid'] ?? null;

        if ($status === 'COMPLETE') {
            echo "Payment successful! Transaction Code: " . $transactionCode;
            // Proceed with order fulfillment
        } else {
            echo "Payment status: " . $status;
        }
    } else {
        echo "No payment data received";
    }
} catch (Exception $e) {
    error_log("Esewa decode error: " . $e->getMessage());
    echo "Error processing payment response";
}

```

--------------------------------

### Configure Esewa Payment Details in PHP

Source: https://context7.com/xentixar/esewa-sdk/llms.txt

Initializes the Esewa payment instance with transaction details like callback URLs, amount, transaction ID, product code, secret key, and various charges. This method is essential before initiating any payment.

```php
<?php

require_once 'vendor/autoload.php';

use Xentixar\EsewaSdk\Esewa;

$esewa = new Esewa();

// Configure payment with required parameters
$esewa->config(
    'https://yourwebsite.com/payment/success',  // success_url
    'https://yourwebsite.com/payment/failure',  // failure_url
    1500.00,                                     // amount
    'TXN-' . uniqid(),                          // transaction_uuid (unique identifier)
    'EPAYTEST',                                  // product_code (default for test)
    '8gBm/:&EnhH.1/q',                          // secret_key (default for test)
    50.00,                                       // tax_amount
    25.00,                                       // product_service_charge
    30.00                                        // product_delivery_charge
);

// Total amount will be automatically calculated: 1500 + 50 + 25 + 30 = 1605.00

```

--------------------------------

### Initialize Esewa Payment Form in PHP (Development)

Source: https://github.com/xentixar/esewa-sdk/blob/main/README.md

Initializes the Esewa payment form for the development environment. No parameters are needed for this.

```php
$esewa->init();
```

--------------------------------

### Initialize Esewa Payment Form in PHP (Production)

Source: https://github.com/xentixar/esewa-sdk/blob/main/README.md

Initializes the Esewa payment form for the production environment by setting the `$production` parameter to true.

```php
$esewa->init(true);
```

--------------------------------

### Initialize Esewa Payment Form Submission in PHP

Source: https://context7.com/xentixar/esewa-sdk/llms.txt

Generates and auto-submits an HTML form to redirect users to the Esewa payment gateway. It takes a boolean to switch between development (false) and production (true) environments and requires payment details to be pre-configured.

```php
<?php

require_once 'vendor/autoload.php';

use Xentixar\EsewaSdk\Esewa;

$esewa = new Esewa();

// Configure payment details
$transactionUuid = 'ORDER-' . time() . '-' . rand(1000, 9999);
$esewa->config(
    'https://yourwebsite.com/payment/verify',
    'https://yourwebsite.com/payment/cancel',
    2000.00,
    $transactionUuid,
    'EPAYTEST',
    '8gBm/:&EnhH.1/q'
);

// For development/testing environment
$esewa->init(false);

// For production environment
// $esewa->init(true);

// This will output an auto-submitting form:
// <form id='esewaForm' action='https://rc-epay.esewa.com.np/api/epay/main/v2/form' method='post'>
//     <input type="hidden" name="amount" value="2000">
//     <input type="hidden" name="tax_amount" value="0">
//     <input type="hidden" name="total_amount" value="2000">
//     <input type="hidden" name="transaction_uuid" value="ORDER-1234567890-5678">
//     <input type="hidden" name="product_code" value="EPAYTEST">
//     <input type="hidden" name="signature" value="base64_encoded_hmac_signature">
//     ... (other fields)
// </form>
// <script>document.getElementById("esewaForm").submit();</script>

```

--------------------------------

### Configure Esewa Payment Details in PHP

Source: https://github.com/xentixar/esewa-sdk/blob/main/README.md

Configures the Esewa payment gateway details, including success and failure URLs, amount, and transaction UUID. Dependencies: Xentixar\EsewaSdk\Esewa.

```php
use Xentixar\EsewaSdk\Esewa;

$esewa = new Esewa();
$esewa->config('https://your-success-url.com', 'https://your-failure-url.com', 1000.00, 'your-transaction-uuid')
```

--------------------------------

### Validate Esewa Transaction Server-Side (PHP)

Source: https://context7.com/xentixar/esewa-sdk/llms.txt

Performs server-side verification of an Esewa transaction by querying Esewa's API using the `validate()` method. This is crucial for fraud prevention and ensures the payment was processed correctly by Esewa. It requires transaction details obtained from the decoded response.

```php
<?php

require_once 'vendor/autoload.php';

use Xentixar\EsewaSdk\Esewa;

$esewa = new Esewa();

// Decode the response first
$responseData = $esewa->decode();

if ($responseData && $responseData['status'] === 'COMPLETE') {
    $totalAmount = $responseData['total_amount'];
    $transactionUuid = $responseData['transaction_uuid'];
    $productCode = $responseData['product_code'] ?? 'EPAYTEST';

    try {
        // Validate with Esewa's server (development environment)
        $validationResponse = $esewa->validate(
            $totalAmount,
            $transactionUuid,
            false,              // false for development, true for production
            $productCode
        );

        // Parse the JSON response
        $validationData = json_decode($validationResponse, true);

        // Sample successful validation response:
        // {
        //     "product_code": "EPAYTEST",
        //     "total_amount": "2000.0",
        //     "transaction_uuid": "ORDER-1234567890-5678",
        //     "transaction_code": "0007Y5T",
        //     "status": "COMPLETE",
        //     "ref_id": "000AB5"
        // }

        if ($validationData && $validationData['status'] === 'COMPLETE') {
            // Transaction is verified and valid
            $refId = $validationData['ref_id'];
            echo "Transaction verified successfully! Reference ID: " . $refId;

            // Update database, complete order, send confirmation email, etc.
            // updateOrderStatus($transactionUuid, 'paid', $refId);

        } else {
            // Transaction validation failed
            echo "Transaction validation failed";
            error_log("Esewa validation failed: " . $validationResponse);
        }

    } catch (Exception $e) {
        error_log("Esewa validation error: " . $e->getMessage());
        echo "Error validating transaction";
    }
} else {
    echo "Invalid or incomplete payment";
}

```

--------------------------------

### Validate Esewa Transaction in PHP

Source: https://github.com/xentixar/esewa-sdk/blob/main/README.md

Validates a transaction by making a cURL request to Esewa's API to check the transaction status. Requires total amount, transaction UUID, and environment flag.

```php
$response = $esewa->validate('1000.00', 'your-transaction-uuid', true);
```
Tokens:
Raw