Download the PHP package sarkhanrasimoghlu/laravel-kapital-bank-payment without Composer

Laravel Kapital Bank Payment

A Laravel package for integrating with the Kapital Bank Checkout Merchant API V1.3. Handles payments, refunds, cancellations, OAuth2 authentication, and webhook verification out of the box.

Requirements

• PHP 8.3+
• Laravel 12.0+ or 13.0+
• Guzzle 7.8+ or 8.0+

Installation

The service provider is auto-discovered. Publish the config and migration:

Configuration

Add these to your .env file:

Optional settings:

Usage

Create a Payment

Payment Method Types

Payment with Metadata

Get Payment Status

Cancel a Payment

Cancel depends on payment status. See the payment state flow in the official documentation.

Full Refund

Partial Refund

Payment can be refunded multiple times if refundable amount is not exceeded.

Get Refund Status

Webhooks

The package automatically registers a POST /kapital-bank/callback route protected by signature verification middleware.

Webhook Payload Format

Kapital Bank sends webhooks in this format:

Supported events: payment_succeeded, payment_canceled.

Signature Verification

The middleware verifies the X-Signature header using Base64-encoded HMAC-SHA256 of the raw request body:

Requests without a valid signature are rejected.

Listening to Events

The package dispatches Laravel events that you can listen to:

Example listener:

Authentication

The package uses OAuth2 client credentials flow (POST /api/oauth2/token). Tokens are automatically:

• Fetched on first API request with grant_type=client_credentials and scope=email
• Cached in Laravel's cache store (default TTL: 3500 seconds)
• Refreshed automatically on 401 responses (exactly once per request)
• Protected against thundering herd with cache locks

You never need to manage tokens manually.

API Endpoints

Transaction Statuses

Error Handling

All exceptions extend KapitalBankException which carries a getContext() method with structured error details:

Security

• OAuth2 Bearer Token injected automatically on every API request
• Token caching with cache lock to prevent thundering herd
• 401 auto-retry with token refresh (exactly once)
• Base64 HMAC-SHA256 webhook signature verification on raw body
• hash_equals() for timing-safe signature comparison
• X-Idempotency-Key UUID on every POST/PUT to prevent double charges
• HTTPS enforcement on all configured URLs (HTTP allowed in local/testing)
• client_secret never logged in any context

Database

The package creates a kapital_bank_transactions table:

Testing

The package includes 86 tests covering:

• Configuration validation
• DTO construction and serialization
• HMAC signature generation and verification (hex + Base64)
• Service layer (create, status, cancel, refund)
• Webhook controller (success, cancel, duplicate, validation)
• Middleware signature verification (raw body)
• OAuth token management (fetch, cache, refresh, errors)

Postman Collection

A ready-to-use Postman collection is included in postman/:

• Kapital_Bank_API_V1.3.postman_collection.json — all endpoints with auto-tests
• Kapital_Bank_API_V1.3.postman_environment.json — environment template

Features:

• Auto token refresh on expiry
• Auto-save payment_id and refund_id between requests
• Auto-generate X-Idempotency-Key UUIDs
• Auto-generate X-Signature for webhook simulation
• Test assertions on every request

License

MIT