✨ feat(api): implementasi autentikasi HMAC dan validasi komprehensif untuk API balance

- Security: validasi HMAC SHA512 untuk semua request, cek timestamp ISO 8601 dengan toleransi 5 menit, autentikasi API key, dan wajib header X-Api-Key, X-Signature, X-Timestamp.
- Input validation: account_number numeric 10 digit & exists, start/end date format YYYY-MM-DD dengan aturan range (start ≤ end ≤ today).
- Perubahan file: update `app/Http/Requests/BalanceSummaryRequest.php` (HMAC check, timestamp check, pesan error, logging) dan `config/webstatement.php` (api_key, secret_key).
- Error handling: konsisten dengan ResponseCode enum; HTTP status 400/401/404; pesan error jelas (Bahasa Indonesia) + logging.
- Testing: Postman collection diperbarui untuk kasus negatif & edge cases; backward compatibility dijaga.
- Breaking changes: endpoint kini mewajibkan 3 header (X-Api-Key, X-Signature, X-Timestamp); account number wajib 10 digit numeric; format tanggal strict.
- ENV: tambahkan `WEBSTATEMENT_API_KEY` dan `WEBSTATEMENT_SECRET_KEY` (dipetakan ke `config/webstatement.php`).

app/Enums/ResponseCode.php

@@ -0,0 +1,140 @@
+<?php
+
+    namespace Modules\Webstatement\Enums;
+
+    use Illuminate\Support\Str;
+
+    /**
+     * Response Code Enum untuk standarisasi response API
+     *
+     * @category Enums
+     * @package  Modules\Webstatement\Enums
+     */
+    enum ResponseCode: string
+    {
+        // Success Codes
+        case SUCCESS = '00';
+
+        // Data Error Codes
+        case INVALID_FIELD          = '01';
+        case MISSING_FIELD          = '02';
+        case INVALID_FORMAT         = '03';
+        case DATA_NOT_FOUND         = '04';
+        case DUPLICATE_REQUEST      = '05';
+        case ACCOUNT_ALREADY_EXISTS = '06';
+        case ACCOUNT_NOT_FOUND      = '07';
+
+        // Auth Error Codes
+        case INVALID_TOKEN = '10';
+        case UNAUTHORIZED  = '11';
+
+        // System Error Codes
+        case SYSTEM_MALFUNCTION  = '96';
+        case TIMEOUT             = '97';
+        case SERVICE_UNAVAILABLE = '98';
+        case GENERAL_ERROR       = '99';
+
+        /**
+         * Mendapatkan pesan response berdasarkan kode
+         *
+         * @return string
+         */
+        public function getMessage(): string
+        {
+            return match($this) {
+                self::SUCCESS                => 'Success',
+                self::INVALID_FIELD          => 'Invalid Field',
+                self::MISSING_FIELD          => 'Missing Field',
+                self::INVALID_FORMAT         => 'Invalid Format',
+                self::DATA_NOT_FOUND         => 'Data Not Found',
+                self::DUPLICATE_REQUEST      => 'Duplicate Request',
+                self::ACCOUNT_ALREADY_EXISTS => 'Account Already Exists',
+                self::ACCOUNT_NOT_FOUND      => 'Account Not Found',
+                self::INVALID_TOKEN          => 'Invalid Token',
+                self::UNAUTHORIZED           => 'Unauthorized',
+                self::SYSTEM_MALFUNCTION     => 'System Malfunction',
+                self::TIMEOUT                => 'Timeout',
+                self::SERVICE_UNAVAILABLE    => 'Service Unavailable',
+                self::GENERAL_ERROR          => 'General Error',
+            };
+        }
+
+        /**
+         * Mendapatkan deskripsi response berdasarkan kode
+         *
+         * @return string
+         */
+        public function getDescription(): string
+        {
+            return match($this) {
+                self::SUCCESS                => 'Permintaan berhasil',
+                self::INVALID_FIELD          => 'Field tertentu tidak sesuai aturan',
+                self::MISSING_FIELD          => 'Field wajib tidak dikirim',
+                self::INVALID_FORMAT         => 'Format salah',
+                self::DATA_NOT_FOUND         => 'Data yang diminta tidak ditemukan',
+                self::DUPLICATE_REQUEST      => 'Request ID sama, sudah pernah diproses',
+                self::ACCOUNT_ALREADY_EXISTS => 'Nomor rekening / username / email sudah terdaftar',
+                self::ACCOUNT_NOT_FOUND      => 'Nomor rekening / akun tidak ditemukan',
+                self::INVALID_TOKEN          => 'Token tidak valid',
+                self::UNAUTHORIZED           => 'Tidak punya akses',
+                self::SYSTEM_MALFUNCTION     => 'Gangguan teknis di server',
+                self::TIMEOUT                => 'Request timeout',
+                self::SERVICE_UNAVAILABLE    => 'Layanan tidak tersedia',
+                self::GENERAL_ERROR          => 'Kesalahan umum',
+            };
+        }
+
+        /**
+         * Mendapatkan HTTP status code berdasarkan response code
+         *
+         * @return int
+         */
+        public function getHttpStatus(): int
+        {
+            return match($this) {
+                self::SUCCESS => 200,
+                self::INVALID_FIELD,
+                self::MISSING_FIELD,
+                self::INVALID_FORMAT => 400,
+                self::DATA_NOT_FOUND,
+                self::ACCOUNT_NOT_FOUND => 404,
+                self::DUPLICATE_REQUEST,
+                self::ACCOUNT_ALREADY_EXISTS => 409,
+                self::INVALID_TOKEN,
+                self::UNAUTHORIZED => 401,
+                self::SYSTEM_MALFUNCTION,
+                self::GENERAL_ERROR       => 500,
+                self::TIMEOUT             => 408,
+                self::SERVICE_UNAVAILABLE => 503,
+            };
+        }
+
+        /**
+         * Membuat response array standar
+         *
+         * @param mixed $data
+         * @param string|null $message
+         * @return array
+         */
+        public function toResponse($data = null, ?string $message = null): array
+        {
+            $response = [
+                'status'               => $this->value == '00' ? true : false,
+                'response_code'        => $this->value,
+                'response_message'     => $this->getMessage() . ($message ? ' | ' . $message : ''),
+            ];
+
+            if (isset($data['errors'])) {
+                $response['errors'] = $data['errors'];
+            } else {
+                $response['data'] = $data;
+            }
+
+            $response['meta'] = [
+                'generated_at'   => now()->toDateTimeString(),
+                'request_id'     => request()->header('X-Request-ID', uniqid('req_'))
+            ];
+
+            return $response;
+        }
+    }

app/Http/Controllers/Api/AccountBalanceController.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace Modules\Webstatement\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Log;
+use Modules\Webstatement\Http\Requests\BalanceSummaryRequest;
+use Modules\Webstatement\Http\Requests\DetailedBalanceRequest;
+use Modules\Webstatement\Services\AccountBalanceService;
+use Modules\Webstatement\Http\Resources\BalanceSummaryResource;
+use Modules\Webstatement\Http\Resources\DetailedBalanceResource;
+use Modules\Webstatement\Enums\ResponseCode;
+use Exception;
+
+class AccountBalanceController extends Controller
+{
+    protected AccountBalanceService $accountBalanceService;
+
+    public function __construct(AccountBalanceService $accountBalanceService)
+    {
+        $this->accountBalanceService = $accountBalanceService;
+    }
+
+    /**
+     * Get account balance summary (opening and closing balance)
+     *
+     * @param BalanceSummaryRequest $request
+     * @return JsonResponse
+     */
+    public function getBalanceSummary(BalanceSummaryRequest $request): JsonResponse
+    {
+        try {
+            $accountNumber = $request->input('account_number');
+            $startDate     = $request->input('start_date');
+            $endDate       = $request->input('end_date');
+
+            Log::info('Account balance summary requested', [
+                'account_number' => $accountNumber,
+                'start_date'     => $startDate,
+                'end_date'       => $endDate,
+                'ip'             => $request->ip(),
+                'user_agent'     => $request->userAgent()
+            ]);
+
+            $result = $this->accountBalanceService->getBalanceSummary(
+                $accountNumber,
+                $startDate,
+                $endDate
+            );
+
+            if (empty($result)) {
+                return response()->json(
+                    ResponseCode::DATA_NOT_FOUND->toResponse(
+                        null,
+                        'Rekening tidak ditemukan'
+                    ),
+                    ResponseCode::DATA_NOT_FOUND->getHttpStatus()
+                );
+            }
+
+            return response()->json(
+                ResponseCode::SUCCESS->toResponse(
+                    (new BalanceSummaryResource($result))->toArray($request),
+
+                ),
+                ResponseCode::SUCCESS->getHttpStatus()
+            );
+
+        } catch (Exception $e) {
+            Log::error('Error getting account balance summary', [
+                'error' => $e->getMessage(),
+                'file'  => $e->getFile(),
+                'line'  => $e->getLine(),
+                'trace' => $e->getTraceAsString()
+            ]);
+
+            $responseCode = match ($e->getCode()) {
+                404 => ResponseCode::DATA_NOT_FOUND,
+                401 => ResponseCode::UNAUTHORIZED,
+                403 => ResponseCode::UNAUTHORIZED,
+                408 => ResponseCode::TIMEOUT,
+                503 => ResponseCode::SERVICE_UNAVAILABLE,
+                400 => ResponseCode::INVALID_FIELD,
+                default => ResponseCode::SYSTEM_MALFUNCTION
+            };
+
+            return response()->json(
+                $responseCode->toResponse(
+                    null,
+                    config('app.debug') ? $e->getMessage() : 'Terjadi kesalahan sistem'
+                ),
+                $responseCode->getHttpStatus()
+            );
+        }
+    }
+}

app/Http/Requests/BalanceSummaryRequest.php

@@ -0,0 +1,317 @@
+<?php
+
+namespace Modules\Webstatement\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Http\Exceptions\HttpResponseException;
+use Modules\Webstatement\Enums\ResponseCode;
+use Modules\Webstatement\Models\AccountBalance;
+
+class BalanceSummaryRequest extends FormRequest
+{
+      /**
+     * Determine if the user is authorized to make this request.
+     *
+     * @return bool
+     */
+    public function authorize(): bool
+    {
+        try {
+            // Ambil parameter dari header
+            $signature = $this->header('X-Signature');
+            $timestamp = $this->header('X-Timestamp');
+            $apiKey    = $this->header('X-Api-Key');
+
+            // Validasi keberadaan header yang diperlukan
+            if (!$signature || !$timestamp || !$apiKey) {
+                Log::warning('HMAC validation failed - missing required headers', [
+                    'signature'  => $signature,
+                    'timestamp'  => $timestamp,
+                    'apiKey'     => $apiKey,
+                    'ip'         => $this->ip(),
+                    'user_agent' => $this->userAgent()
+                ]);
+                return false;
+            }
+
+            // Validasi API key dari config
+            $expectedApiKey = config('webstatement.api_key');
+            if ($apiKey !== $expectedApiKey) {
+                Log::warning('HMAC validation failed - invalid API key', [
+                    'provided_api_key' => $apiKey,
+                    'expected_api_key' => $expectedApiKey,
+                    'ip'               => $this->ip(),
+                    'user_agent'       => $this->userAgent()
+                ]);
+                return false;
+            }
+
+              // Ambil secret key dari config
+            $secretKey = config('webstatement.secret_key');
+
+              // Ambil parameter untuk validasi HMAC
+            $httpMethod  = $this->method();
+            $relativeUrl = $this->path();
+            $requestBody = $this->getContent();
+
+            // Validasi HMAC signature
+            $isValid = validateHmac512(
+                $httpMethod,
+                $relativeUrl,
+                $apiKey,
+                $requestBody,
+                $timestamp,
+                $secretKey,
+                $signature
+            );
+
+            if (!$isValid) {
+                Log::warning('HMAC validation failed - invalid signature', [
+                    'http_method'  => $httpMethod,
+                    'relative_url' => $relativeUrl,
+                    'api_key'      => $apiKey,
+                    'timestamp'    => $timestamp,
+                    'ip'           => $this->ip(),
+                    'user_agent'   => $this->userAgent()
+                ]);
+            }
+
+            return $isValid;
+
+        } catch (\Exception $e) {
+            Log::error('HMAC validation error', [
+                'error'      => $e->getMessage(),
+                'file'       => $e->getFile(),
+                'line'       => $e->getLine(),
+                'ip'         => $this->ip(),
+                'user_agent' => $this->userAgent()
+            ]);
+            return false;
+        }
+    }
+
+      /**
+     * Get the validation rules that apply to the request.
+     *
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'account_number' => [
+                'required',
+                'string',
+                'max:10',
+                'min:10',
+                'exists:account_balances,account_number',
+                'regex:/^[0-9]+$/'  // Numeric only
+            ],
+            'start_date' => [
+                'required',
+                'date_format:Y-m-d',
+                'before_or_equal:end_date',
+                'after_or_equal:1900-01-01',
+                'before_or_equal:today'
+            ],
+            'end_date' => [
+                'required',
+                'date_format:Y-m-d',
+                'after_or_equal:start_date',
+                'after_or_equal:1900-01-01',
+                'before_or_equal:today'
+            ],
+        ];
+    }
+
+      /**
+     * Get custom messages for validator errors.
+     *
+     * @return array<string, string>
+     */
+    public function messages(): array
+    {
+        return [
+            'account_number.exists'      => 'Nomor rekening tidak ditemukan.',
+            'account_number.required'    => 'Nomor rekening wajib diisi.',
+            'account_number.string'      => 'Nomor rekening harus berupa teks.',
+            'account_number.max'         => 'Nomor rekening maksimal :max karakter.',
+            'account_number.min'         => 'Nomor rekening minimal :min karakter.',
+            'account_number.regex'       => 'Nomor rekening hanya boleh mengandung angka.',
+            'start_date.required'        => 'Tanggal awal wajib diisi.',
+            'start_date.date_format'     => 'Format tanggal awal harus YYYY-MM-DD.',
+            'start_date.before_or_equal' => 'Tanggal awal harus sebelum atau sama dengan tanggal akhir.',
+            'end_date.required'          => 'Tanggal akhir wajib diisi.',
+            'end_date.date_format'       => 'Format tanggal akhir harus YYYY-MM-DD.',
+            'end_date.after_or_equal'    => 'Tanggal akhir harus sesudah atau sama dengan tanggal awal.',
+            'end_date.before_or_equal'   => 'Tanggal akhir harus sebelum atau sama dengan hari ini.',
+        ];
+    }
+
+      /**
+     * Handle a failed validation attempt.
+     *
+     * @param  \Illuminate\Contracts\Validation\Validator  $validator
+     * @return void
+     *
+     * @throws \Illuminate\Validation\ValidationException
+     */
+    protected function failedValidation($validator)
+    {
+        $errors = $validator->errors();
+
+        if($errors->has('account_number') && $errors->first('account_number') === 'Nomor rekening tidak ditemukan.') {
+            throw new HttpResponseException(
+                response()->json(
+                    ResponseCode::ACCOUNT_NOT_FOUND->toResponse(
+                        null,
+                        'Nomor rekening tidak ditemukan'
+                    ),
+                    ResponseCode::ACCOUNT_NOT_FOUND->getHttpStatus()
+                )
+            );
+        }
+
+        throw new HttpResponseException(
+            response()->json(
+                ResponseCode::INVALID_FIELD->toResponse(
+                    ['errors' => $errors->all()],
+                    'Validasi gagal'
+                ),
+                ResponseCode::INVALID_FIELD->getHttpStatus()
+            )
+        );
+    }
+
+    /**
+     * Handle failed authorization.
+     *
+     * @return void
+     *
+     * @throws \Illuminate\Auth\Access\AuthorizationException
+     */
+    protected function failedAuthorization()
+    {
+        $xApiKey = $this->header('X-Api-Key');
+        $xSignature = $this->header('X-Signature');
+        $xTimestamp = $this->header('X-Timestamp');
+
+        $expectedApiKey = config('webstatement.api_key');
+
+        if(!$xApiKey){
+            throw new HttpResponseException(
+                response()->json(
+                    ResponseCode::INVALID_FIELD->toResponse(
+                        ['errors' => ['X-Api-Key' => 'API Key wajib diisi']],
+                        'Validasi gagal'
+                    ),
+                    ResponseCode::INVALID_FIELD->getHttpStatus()
+                )
+            );
+        }
+
+        if(!$xSignature){
+            throw new HttpResponseException(
+                response()->json(
+                    ResponseCode::INVALID_FIELD->toResponse(
+                        ['errors' => ['X-Signature' => 'Signature wajib diisi']],
+                        'Validasi gagal'
+                    ),
+                    ResponseCode::INVALID_FIELD->getHttpStatus()
+                )
+            );
+        }
+
+        if(!$xTimestamp){
+            throw new HttpResponseException(
+                response()->json(
+                    ResponseCode::INVALID_FIELD->toResponse(
+                        ['errors' => ['X-Timestamp' => 'Timestamp wajib diisi']],
+                        'Validasi gagal'
+                    ),
+                    ResponseCode::INVALID_FIELD->getHttpStatus()
+                )
+            );
+        }
+
+        // Validasi format timestamp ISO 8601
+        if (!preg_match('/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/', $xTimestamp)) {
+            throw new HttpResponseException(
+                response()->json(
+                    ResponseCode::INVALID_FIELD->toResponse(
+                        ['errors' => ['X-Timestamp' => 'Format timestamp tidak valid. Gunakan format ISO 8601 (YYYY-MM-DDTHH:MM:SS.sssZ)']],
+                        'Validasi gagal'
+                    ),
+                    ResponseCode::INVALID_FIELD->getHttpStatus()
+                )
+            );
+        }
+
+        // Validasi timestamp tidak lebih dari 5 menit dari waktu sekarang
+        try {
+            $timestamp = new \DateTime($xTimestamp);
+            $now = new \DateTime();
+            $diff = $now->getTimestamp() - $timestamp->getTimestamp();
+
+            if (abs($diff) > 300) { // 5 menit = 300 detik
+                throw new HttpResponseException(
+                    response()->json(
+                        ResponseCode::INVALID_FIELD->toResponse(
+                            ['errors' => ['X-Timestamp' => 'Timestamp expired. Maksimal selisih 5 menit dari waktu sekarang']],
+                            'Validasi gagal'
+                        ),
+                        ResponseCode::INVALID_FIELD->getHttpStatus()
+                    )
+                );
+            }
+        } catch (\Exception $e) {
+            throw new HttpResponseException(
+                response()->json(
+                    ResponseCode::INVALID_FIELD->toResponse(
+                        ['errors' => ['X-Timestamp' => 'Timestamp tidak dapat diproses']],
+                        'Validasi gagal'
+                    ),
+                    ResponseCode::INVALID_FIELD->getHttpStatus()
+                )
+            );
+        }
+
+        // Cek apakah ini karena invalid API key
+        if ($xApiKey !== $expectedApiKey) {
+            throw new HttpResponseException(
+                response()->json(
+                    ResponseCode::INVALID_TOKEN->toResponse(
+                        null,
+                        'API Key tidak valid'
+                    ),
+                    ResponseCode::INVALID_TOKEN->getHttpStatus()
+                )
+            );
+        }
+
+        // Untuk kasus HMAC signature tidak valid
+        throw new HttpResponseException(
+            response()->json(
+                ResponseCode::UNAUTHORIZED->toResponse(
+                    null,
+                    'Signature tidak valid'
+                ),
+                ResponseCode::UNAUTHORIZED->getHttpStatus()
+            )
+        );
+    }
+
+    /**
+     * Prepare the data for validation.
+     *
+     * @return void
+     */
+    protected function prepareForValidation(): void
+    {
+        Log::info('Balance summary request received', [
+            'input'      => $this->all(),
+            'ip'         => $this->ip(),
+            'user_agent' => $this->userAgent()
+        ]);
+    }
+}

app/Http/Resources/BalanceSummaryResource.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Modules\Webstatement\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Support\Str;
+
+class BalanceSummaryResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @param  Request  $request
+     * @return array
+     */
+    public function toArray($request): array
+    {
+        return [
+            'account_number' => $this['account_number'],
+            'period' => [
+                'start_date' => $this['period']['start_date'],
+                'end_date' => $this['period']['end_date'],
+            ],
+            'opening_balance' => [
+                'date' => $this['opening_balance']['date'],
+                'balance' => $this['opening_balance']['balance'],
+                'formatted_balance' => number_format($this['opening_balance']['balance'], 2, ',', '.'),
+            ],
+            'closing_balance' => [
+                'date' => $this['closing_balance']['date'],
+                'balance' => $this['closing_balance']['balance'],
+                'formatted_balance' => number_format($this['closing_balance']['balance'], 2, ',', '.'),
+                'base_balance' => [
+                    'date' => $this['closing_balance']['base_balance']['date'],
+                    'balance' => $this['closing_balance']['base_balance']['balance'],
+                    'formatted_balance' => number_format($this['closing_balance']['base_balance']['balance'], 2, ',', '.'),
+                ],
+                'transactions_on_end_date' => $this['closing_balance']['transactions_on_end_date'],
+                'formatted_transactions_on_end_date' => number_format($this['closing_balance']['transactions_on_end_date'], 2, ',', '.'),
+            ]
+        ];
+    }
+}

app/Providers/BalanceServiceProvider.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Modules\Webstatement\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use Modules\Webstatement\Services\AccountBalanceService;
+
+class BalanceServiceProvider extends ServiceProvider
+{
+    /**
+     * Register the service provider.
+     *
+     * @return void
+     */
+    public function register(): void
+    {
+        $this->app->singleton(AccountBalanceService::class, function ($app) {
+            return new AccountBalanceService();
+        });
+    }
+
+    /**
+     * Get the services provided by the provider.
+     *
+     * @return array<string>
+     */
+    public function provides(): array
+    {
+        return [AccountBalanceService::class];
+    }
+}

app/Providers/WebstatementServiceProvider.php

@@ -57,6 +57,7 @@ class WebstatementServiceProvider extends ServiceProvider
     {
         $this->app->register(EventServiceProvider::class);
         $this->app->register(RouteServiceProvider::class);
+        $this->app->register(BalanceServiceProvider::class);
         $this->app->bind(UpdateAtmCardBranchCurrencyJob::class);
     }
 

app/Services/AccountBalanceService.php

@@ -0,0 +1,130 @@
+<?php
+
+namespace Modules\Webstatement\Services;
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Carbon\Carbon;
+use Modules\Webstatement\Models\AccountBalance;
+use Modules\Webstatement\Models\StmtEntry;
+
+class AccountBalanceService
+{
+    /**
+     * Get balance summary (opening and closing balance)
+     *
+     * @param string $accountNumber
+     * @param string $startDate
+     * @param string $endDate
+     * @return array
+     */
+    public function getBalanceSummary(string $accountNumber, string $startDate, string $endDate): array
+    {
+        return DB::transaction(function () use ($accountNumber, $startDate, $endDate) {
+            Log::info('Calculating balance summary', [
+                'account_number' => $accountNumber,
+                'start_date'     => $startDate,
+                'end_date'       => $endDate
+            ]);
+
+              // Convert dates to Carbon instances
+            $startDateCarbon = Carbon::parse($startDate);
+            $endDateCarbon   = Carbon::parse($endDate);
+
+              // Get opening balance (balance from previous day)
+            $openingBalanceDate = $startDateCarbon->copy()->subDay();
+            $openingBalance     = $this->getAccountBalance($accountNumber, $openingBalanceDate);
+
+              // Get closing balance date (previous day from end date)
+            $closingBalanceDate = $endDateCarbon->copy()->subDay();
+            $closingBalanceBase = $this->getAccountBalance($accountNumber, $closingBalanceDate);
+
+              // Get transactions on end date
+            $transactionsOnEndDate = $this->getTransactionsOnDate($accountNumber, $endDate);
+
+              // Calculate closing balance
+            $closingBalance = $closingBalanceBase + $transactionsOnEndDate;
+
+            $result = [
+                'account_number' => $accountNumber,
+                'period'         => [
+                    'start_date' => $startDate,
+                    'end_date'   => $endDate
+                ],
+                'opening_balance' => [
+                    'date'              => $openingBalanceDate->format('Y-m-d'),
+                    'balance'           => $openingBalance,
+                    'formatted_balance' => number_format($openingBalance, 2)
+                ],
+                'closing_balance' => [
+                    'date'              => $endDate,
+                    'balance'           => $closingBalance,
+                    'formatted_balance' => number_format($closingBalance, 2),
+                    'base_balance'      => [
+                        'date'              => $closingBalanceDate->format('Y-m-d'),
+                        'balance'           => $closingBalanceBase,
+                        'formatted_balance' => number_format($closingBalanceBase, 2)
+                    ],
+                    'transactions_on_end_date'           => $transactionsOnEndDate,
+                    'formatted_transactions_on_end_date' => number_format($transactionsOnEndDate, 2)
+                ]
+            ];
+
+            Log::info('Balance summary calculated successfully', $result);
+
+            return $result;
+        });
+    }
+
+    /**
+     * Get account balance for specific date
+     *
+     * @param string $accountNumber
+     * @param Carbon $date
+     * @return float
+     */
+    private function getAccountBalance(string $accountNumber, Carbon $date): float
+    {
+        $balance = AccountBalance::where('account_number', $accountNumber)
+            ->where('period', $date->format('Ymd'))
+            ->value('actual_balance');
+
+        if ($balance === null) {
+            Log::warning('Account balance not found', [
+                'account_number' => $accountNumber,
+                'date'           => $date->format('Y-m-d'),
+                'period'         => $date->format('Ymd')
+            ]);
+            return 0.00;
+        }
+
+        return (float) $balance;
+    }
+
+    /**
+     * Get transactions on specific date
+     *
+     * @param string $accountNumber
+     * @param string $date
+     * @return float
+     */
+    private function getTransactionsOnDate(string $accountNumber, string $date): float
+    {
+        $total = StmtEntry::where('account_number', $accountNumber)
+            ->whereDate('value_date', $date)
+            ->sum(DB::raw('CAST(amount_lcy AS DECIMAL(15,2))'));
+
+        return (float) $total;
+    }
+
+    /**
+     * Validate if account exists
+     *
+     * @param string $accountNumber
+     * @return bool
+     */
+    public function validateAccount(string $accountNumber): bool
+    {
+        return AccountBalance::where('account_number', $accountNumber)->exists();
+    }
+}

config/config.php

@@ -5,4 +5,17 @@ return [
 
     // ZIP file password configuration
     'zip_password' => env('WEBSTATEMENT_ZIP_PASSWORD', 'statement123'),
+    /*
+    |--------------------------------------------------------------------------
+    | API Configuration
+    |--------------------------------------------------------------------------
+    |
+    | These configuration values are used for API authentication using HMAC
+    | signature validation. These keys are used to validate incoming API
+    | requests and ensure secure communication.
+    |
+    */
+
+    'api_key' => env('API_KEY'),
+    'secret_key' => env('SECRET_KEY'),
 ];

routes/api.php

@@ -3,7 +3,13 @@
     use Illuminate\Support\Facades\Route;
     use Modules\Webstatement\Http\Controllers\CustomerController;
     use Modules\Webstatement\Http\Controllers\EmailBlastController;
+    use Modules\Webstatement\Http\Controllers\Api\AccountBalanceController;
 
     Route::post('/email-blast', [EmailBlastController::class, 'sendEmailBlast']);
     Route::get('/email-blast-history', [EmailBlastController::class, 'getEmailBlastHistory']);
     Route::get('/customers/search', [CustomerController::class, 'search']);
+
+    // Account Balance API Routes
+    Route::prefix('balance')->group(function () {
+        Route::post('/', [AccountBalanceController::class, 'getBalanceSummary']);
+    });