DEV Community: Pemba Sherpa

Step-by-Step Guide to Integrate eSewa EPAY v2 with Laravel and Livewire

Pemba Sherpa — Fri, 27 Jun 2025 01:19:50 +0000

This blog guides you through integrating eSewa v2 into your Laravel application using Livewire. I assume you already have basic knowledge of Livewire, and that Laravel and Livewire are installed and set up.

Step 1: Create the eSewa Configuration File

First, create a config file (e.g. config/esewa.php) where you can add your eSewa product code, secret key, production URL, and sandbox URL. Make sure to add these values to your .env file as well.

<?php

declare(strict_types=1);

return [
    'product_code' => env('ESEWA_PRODUCT_CODE'),
    'secret' => env('ESEWA_SECRET'),
    'production_url' => env('ESEWA_PRODUCTION_URL'),
    'sandbox_url' => env('ESEWA_SANDBOX_URL'),
];

Step 2: Create Your Checkout Component

Assuming you already have a Livewire Checkout Component, you will handle the fields required for the eSewa checkout page inside it. You can name the method anything you like to process this logic; in my case, I used a method called save().

According to eSewa documentation there are a few important fields to keep in mind such as transaction_uuid and signature. The transaction_uuid needs be unique for every transaction.

Step 3: Create the Esewa Helper Class (Optional)

To keep your code clean, I created a helper class Esewa.php that contains reusable logic like fetching credentails and generating signatures.

<?php

declare(strict_types=1);

namespace App\Helpers;

use App\Models\Client;

class Esewa
{
    public static function generateSignature(array $fields): string
    {
        $signatureMessage = collect($fields)->map(fn ($value, $key): string => "{$key}={$value}")->implode(',');

        return base64_encode(hash_hmac('sha256', $signatureMessage, config('esewa.secret'), true));
    }

    public static function getCredentials(): array
    {
        $productCode = config('esewa.product_code');
        $secret = config('esewa.secret');

        return [
            'product_code' => $productCode,
            'secret' => $secret,
        ];
    }
}

Signature Explanation

According to eSewa's documentation, to generate the signature, you need to includes these fields along with their values: total_amount, transaction_uuid, and product_code.

For example:

use App\Helpers\Esewa;

['product_code' => $productCode,'secret' => $secret] = Esewa::getCredentials();

$signatureFields = [
  'total_amount' => $this->cart->total,
  'transaction_uuid' => $transactionUuid,
  'product_code' => $productCode,
];

$signature = Esewa::generateSignature($signatureFields, $secret);

In the code, I created an array $signatureFields containing the required fields for the signature along with their values and passed it to the generateSignature function.

The signature message should look like this:

total_amount=100,transaction_uuid=128481264,product_code=EPAYTEST

After that, you need to hash the string using HMAC-SHA256 and then encode it in base64. This process is implemented in the generateSignature function.

Step 4: Creating the form fields for Esewa Checkout Page

All the required fields are mentioned in the eSewa documentation. Please refer to the official documentation here.

 $data = [
        'amount' => $this->cart->sub_total,
        'tax_amount' => $this->cart->vat,
        'total_amount' => $this->cart->total,
        'transaction_uuid' => $transactionUuid,
        'product_code' => $productCode,
        'product_service_charge' => $this->cart->service_charge,
        'product_delivery_charge' => 0,
        'success_url' => route('esewa.success'),
        'failure_url' => route('esewa.failure'),
        'signed_field_names' => 'total_amount,transaction_uuid,product_code',
        'signature' => $signature,
    ];

$this->dispatch('esewa-form-submit', data: $data);

Step 5: Handling the eSewa Form Submission Using JavaScript

eSewa does not support backend checkout directly. Instead, you must create an HTML form with the required fields and submit it to eSewa’s URL. To achieve this, we will use JavaScript to dynamically create and submit the form.

To avoid exposing JS logic directly in your Blade templates, I created a JavaScript module esewa-form.js in resources/js:

export default () => ({
    formSubmit(data, isProduction = false){
        const form = document.createElement('form');
        form.method = 'POST';
        form.action = isProduction 
            ? 'https://epay.esewa.com.np/api/epay/main/v2/form'
            : 'https://rc-epay.esewa.com.np/api/epay/main/v2/form';

        Object.entries(data).forEach(([key, value]) => {
            const input = document.createElement('input');
            input.type = 'hidden';
            input.id = key;
            input.name = key;
            input.value = value;
            form.appendChild(input);
        });

        document.body.appendChild(form);
        form.submit();
    }
});

import './bootstrap';
import esewaForm from './esewa-form';

document.addEventListener('alpine:init', () => {
    Alpine.data('esewa', esewaForm);
});

Step 6: Listen for the Emit Event in Blade

In your checkout.blade.php, add a <div> and use Alpine.js to listen for the Livewire esewa-form-submit event:

<div x-data="esewa" @esewa-form-submit.window="formSubmit($event.detail.data)">
  <!-- Your checkout form goes here -->
</div>

Important: Don't forget to include Livewire’s @livewireScriptConfig as explained in the Livewire docs. Without it, it doesn't work.

Step 7: Handling the Payment Success Response

After payment completion, eSewa redirects to your success route with a base64-encoded response string. You need to decode it and verify the signature:

$transactionResponse = json_decode(base64_decode($request->data), true);

A typical response looks like:

{
  "transaction_code": "000AWEO",
  "status": "COMPLETE",
  "total_amount": 1000.0,
  "transaction_uuid": "250610-162413",
  "product_code": "EPAYTEST",
  "signed_field_names": "transaction_code,status,total_amount,transaction_uuid,product_code,signed_field_names",
  "signature": "62GcfZTmVkzhtUeh+QJ1AqiJrjoWWGof3U+eTPTZ7fA="
}

According to the eSewa documentation, it is necessary to verify the response signature by generating a new signature from the response data and comparing it with the one provided in the response. To verify the response signature, you generate a signature from the response data excluding the signature field:

use Illuminate\Support\Arr;

$signatureFields = Arr::except($transactionResponse, ['signature']);

$signature = Esewa::generateSignature($signatureFields, config('esewa.secret'));

if ($signature !== $transactionResponse['signature']) {
    // Cancel the transaction due to signature mismatch
    return ;
}

Step 8: Check Payment Status Using eSewa API

Once the signature is verified, it is also necessary to confirm the payment status. To do this, we create an service EsewaService.php file that calls eSewa’s payment status API.

<?php

declare(strict_types=1);

namespace App\Services;

use Illuminate\Support\Facades\Http;

class EsewaService
{
    public static function paymentStatusCheck(array $data): array
    {
        $url = match (app()->environment()) {
            'production' => config('esewa.production_url'),
            default => config('esewa.sandbox_url')
        } . 'transaction/status/?';

        $urlWithQueryParams = $url . http_build_query([
            'product_code' => $data['product_code'],
            'total_amount' => $data['total_amount'],
            'transaction_uuid' => $data['transaction_uuid'],
        ]);

        $response = Http::get($urlWithQueryParams)->json();

        return $response;
    }
}

Call this service after verifying the signature:

$statusResponse = EsewaService::paymentStatusCheck($transactionResponse);

if ($statusResponse['status'] === 'COMPLETE') {
    // Payment successful, proceed with creating order
}

Bonus Tip:

If you want to store customer information (like name, email, and contact) when they submit the checkout form, you can use session to store the data and clear it after payment success or failure.

If you are working with a team, consider using Data Transfer Objects (DTOs) to clearly define response fields with their types.

If you have any questions or would like me to share a GitHub repo or full working example, feel free to reach out or leave a comment.

Happy coding! 🚀

Building React Project with Vite, TailwindCSS, Docker, and Deploying to DigitalOcean

Pemba Sherpa — Thu, 08 May 2025 07:12:36 +0000

In this tutorial, we will guide through the process of setting up a React Project using Vite as build tool, integrating TailwindCSS for styling, containerizing the application with Docker for both development and production environments, and deploying it to DigitalOcean.

This tutorial assumes you have a basic understanding of Docker.

1. Install React

First, create a new react project using Vite. For installation you can refer to this link.

2. Install TailwindCSS with Vite

Next, install the TailwindCSS by following this guide.

Once you have both React and TailwindCSS set up and working locally, we can process to containerize the application using Docker.

3. Creating a Dockerfile

We will create a Dockerfile that supports both the development and production environments. To achieve this, we used multi-stage build, which allows us to define multiple FROM within a single Dockerfile. To learn more about multi-stage builds, click here.

In our Dockerfile it consists of four stages. They are:

Base Stage

FROM node:22-alpine3.21 AS base
WORKDIR /app
COPY package*.json ./
RUN npm ci 
COPY . .

We start by creating a base stage using AS keyword. This stage install the exact necessary dependencies from package-lock.json and copies the files from host to container.

Dev Stage

FROM base AS dev
EXPOSE 5137
CMD ["npm","run","dev"]

In the dev stage, we build on top of the base stage. We then expose port 5137, which is the default port for the Vite development server. Finally, we start the development server using npm run dev.

Build Stage

FROM base AS build
RUN npm run build

In this stage, we build on top of the base stage and execute the npm run build command to generate optimized static assets for production.

Production Stage

FROM nginx:1.28.0-alpine AS prod
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx","-g","daemon off;"]

In the prod stage, we serve the static files generated by the build stage. We using Nginx, a lightweight and high-performance web server.

COPY --from=build /app/dist /usr/share/nginx/html: This command copies the static files from the build stage (located in app/dist) to Nginx's default directory (/usr/share/nginx/html), making them accessible for serving.
CMD ["nginx","-g","daemon off;"]: This runs Nginx in the foreground to keep the container running.
EXPOSE 80: This command exposes port 80, which is the default port for HTTP traffic and is used by Nginx to serve web content.

Overall, the Dockerfile looks like this

FROM node:22-alpine-3.21 as base
WORKDIR /app
COPY package*.json .
RUN npm install && npm install tailwindcss @tailwindcss/vite
COPY . .

FROM base AS dev
EXPOSE 5137
CMD ["npm","run","dev"]

FROM base AS build
RUN npm run build

FROM nginx:1.28.0-alpine as prod
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx","-g","daemon off;"]

4. Creating a Docker Compose

Once, the Dockerfile is created, we create a docker-compose.dev.yml
file to build the image and run the container, simplifying the process of managing services and configurations.

version: '3.8'
services:
  web:
    build: 
      context: .
      target: dev
    image: react-vite-project:dev
    container_name: react-vite-project-dev
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "5173:5173"
    environment:
      - CHOKIDAR_USEPOLLING=true

In the file, we need to specify the target stage dev for our development environment using target:dev. We then mount the project directory to /app inside the container to enable live changes, while ignoring the node modules directory. Additionally, we set the CHOKIDAR_USEPOLLING environment variable to ensure proper file watching.

5. Vite Configuration

In the vite.config.ts we need to configure the server settings and use polling for file changes to ensure proper-file watching, especially in environments like Docker.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
  ],
  server: {
    host: true,
    strictPort: true,
    port: 5173,
    watch: {
      usePolling: true
    }
  }
})

6. Run Docker Compose

Once everything is configured, you can run the following command:
docker compose -f docker-compose-dev.yml up

This command will build the Docker image and start the container.
You should see similar output in your terminal:

Once the container is up and running, you can access the application at (http://localhost:5173).

7. DigitalOcean Configuration

Now, let's configured the Digital Ocean to deploy our application.

Setup Container Registry

First, we use DigitalOcean Container Registry to store the private Docker image. To configure the registry, you can follow this instructions.

Setup App Platform

After configuring the registry, we set up the App Platform. You can easily create an App Platform from the DigitalOcean dashboard by clicking Create and selecting App Platform.

Now, when creating the app platform, select the Container Image and choose DigitalOcean Container Registry, since our image is stored there and enable AutoDeploy so that the app automatically updates whenever a new image is pushed to the registry.

8. Creating GitHub Action

To build the Docker image and push it to the container registry, we use GitHub Actions. You can create a GitHub Action by going to the Actions tab in your repository and clicking New Workflow. Then, select the Docker Image workflow template to get started.

Once GitHub Action is created, we need to configure it to work with DigitalOcean Container Registry.

To authenticate the GitHub Action with DigitalOcean, follow these steps:

Create a Personal Access Token: You can follow this guide to create a token from your DigitalOcean account.
In your GitHub repository, go to Settings → Secrets and variables → Actions.
Add the following secrets:
- DO_USERNAME: The token name.
- DO_ACCESS_TOKEN: The token value.

name: Docker Image CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:

  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Log in to DigitalOcean Container Registry
      uses: docker/login-action@v3
      with:
        registry: registry.digitalocean.com
        username: ${{secrets.DO_USERNAME}}
        password: ${{secrets.DO_ACCESS_TOKEN}}

    - name: Build the Docker image
      run: |
        docker build . --file Dockerfile --target prod --tag react-vite-project:latest 
        docker tag react-vite-project:latest registry.digitalocean.com/private-docker-images/react-vite-project:latest

    - name: Push Docker Image to Digital Ocean Registry
      run: |
        docker push registry.digitalocean.com/private-docker-images/react-vite-project:latest

In the GitHub Action, we need to specify the prod target and tag the image so it can be pushed to the DigitalOcean Container Registry. Finally, we push the image to the registry.

Once the image is pushed to the registry, you can view it in the Container Registry.

Once the image is pushed, it is automatically deployed on App Platform. You can click the link above to view it.

Conclusion

In this guide, we walked through setting up a React, TailwindCSS application using Vite, containerizing it with Docker, automating the build and deployment process with GitHub Actions, and deploying it using DigitalOcean App Platform.

If you found this helpful, feel free to share it or leave a comment. Happy coding!