dk_payment_gateway 1.0.0

data/README.md

@@ -0,0 +1,296 @@
+# DK Payment Gateway Ruby Gem
+
+A Ruby client library for integrating with the Digital Kidu (DK) Payment Gateway API. This gem provides a clean, easy-to-use interface for:
+
+- Pull payments (payment gateway authorization and debit)
+- Intra-bank transactions (DK to DK transfers)
+- QR code generation for payments
+- Transaction status verification
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dk_payment_gateway'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install dk_payment_gateway
+```
+
+## Configuration
+
+Configure the gem with your API credentials:
+
+```ruby
+DkPaymentGateway.configure do |config|
+  config.base_url = "http://internal-gateway.uat.digitalkidu.bt/api/dkpg"
+  config.api_key = "98cf3639-df33-4587-9d36-dae9d2bb974c"
+  config.username = "your_username"
+  config.password = "your_password"
+  config.client_id = "0fefeac4-e969-46ce-8d02-92db4ed8e62e"
+  config.client_secret = "your_client_secret"
+  config.source_app = "SRC_AVS_0201"
+  config.timeout = 30
+  config.open_timeout = 10
+end
+```
+
+## Usage
+
+### Initialize Client and Authenticate
+
+```ruby
+# Create a client instance
+client = DkPaymentGateway.client
+
+# Authenticate and fetch private key for signing
+client.authenticate!
+```
+
+### Pull Payment (Payment Gateway)
+
+#### 1. Authorization (Account Inquiry and OTP Request)
+
+```ruby
+# Generate STAN number
+stan = DkPaymentGateway::PullPayment.generate_stan("0201")
+
+# Request authorization
+response = client.pull_payment.authorize(
+  transaction_datetime: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+  stan_number: stan,
+  transaction_amount: 100.00,
+  transaction_fee: 5.00,
+  payment_desc: "Payment for Invoice #123",
+  account_number: "110158212197",
+  account_name: "John Doe",
+  email_id: "customer@example.com",
+  phone_number: "17811440",
+  remitter_account_number: "770182571",
+  remitter_account_name: "Jane Smith",
+  remitter_bank_id: "1040"
+)
+
+# Response contains:
+# {
+#   "bfs_txn_id" => "523400081332",
+#   "stan_number" => "020111571912",
+#   "account_number" => "110158212197",
+#   "remitter_account_number" => "770182571"
+# }
+
+bfs_txn_id = response["bfs_txn_id"]
+```
+
+#### 2. Debit Request (Complete Payment with OTP)
+
+```ruby
+response = client.pull_payment.debit(
+  request_id: "REQ_#{Time.now.to_i}",
+  bfs_txn_id: bfs_txn_id,
+  bfs_remitter_otp: "123456",
+  bfs_order_no: "ORDER_12345" # optional
+)
+
+# Response contains:
+# {
+#   "bfs_txn_id" => "523700081429",
+#   "code" => "00",
+#   "description" => "Approved"
+# }
+```
+
+### Intra-Bank Transactions (DK to DK)
+
+#### 1. Beneficiary Account Inquiry
+
+```ruby
+response = client.intra_transaction.account_inquiry(
+  request_id: "REQ_#{Time.now.to_i}",
+  amount: 300.00,
+  currency: "BTN",
+  bene_bank_code: "1060",
+  bene_account_number: "100100148337",
+  source_account_name: "Rinzin Jamtsho",
+  source_account_number: "100100365856"
+)
+
+# Response contains:
+# {
+#   "inquiry_id" => "DKBT--ptr2aseR2Ch85QY-AufVg-776768",
+#   "account_name" => "Rinzin Jamtsho"
+# }
+
+inquiry_id = response["inquiry_id"]
+```
+
+#### 2. Fund Transfer
+
+```ruby
+response = client.intra_transaction.fund_transfer(
+  request_id: "REQ_#{Time.now.to_i}",
+  inquiry_id: inquiry_id,
+  transaction_datetime: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+  transaction_amount: 300.00,
+  currency: "BTN",
+  payment_type: "INTRA",
+  source_account_name: "Rinzin Jamtsho",
+  source_account_number: "100100365856",
+  bene_cust_name: "Dorji Wangchuk",
+  bene_account_number: "100100148337",
+  bene_bank_code: "1060",
+  narration: "Payment for services"
+)
+
+# Response contains:
+# {
+#   "inquiry_id" => "DKBT-gllIxZ7rSoqkAOzZj4i2HQ-554567",
+#   "txn_status_id" => "6f67d4ca-c8f9-49a5-8c2d-96c8b07c74e5"
+# }
+```
+
+### QR Code Generation
+
+```ruby
+# Generate Static QR (amount = 0, payer enters amount)
+response = client.qr_payment.generate_qr(
+  request_id: "REQ_#{Time.now.to_i}",
+  currency: "BTN",
+  bene_account_number: "100100148337",
+  amount: 0,
+  mcc_code: "5411",
+  remarks: "Payment for invoice #1234"
+)
+
+# Generate Dynamic QR (fixed amount)
+response = client.qr_payment.generate_qr(
+  request_id: "REQ_#{Time.now.to_i}",
+  currency: "BTN",
+  bene_account_number: "100100148337",
+  amount: 50.05,
+  mcc_code: "5411",
+  remarks: "Payment for invoice #1234"
+)
+
+# Response contains:
+# {
+#   "image" => "base64_encoded_image_data"
+# }
+
+# Save QR image to file
+client.qr_payment.save_qr_image(response["image"], "qr_code.png")
+```
+
+### Transaction Status Verification
+
+#### Check Current Day Transaction
+
+```ruby
+response = client.transaction_status.check_current_day(
+  request_id: "REQ_#{Time.now.to_i}",
+  transaction_id: "test_txn_update23567",
+  bene_account_number: "100100365856"
+)
+
+# Response contains:
+# {
+#   "meta_info" => {...},
+#   "status" => {
+#     "status" => "0",
+#     "status_desc" => "Successfully completed",
+#     "txn_ts" => "2025-09-18 12:32:21",
+#     "amount" => "150.00",
+#     "debit_account" => "200133679",
+#     "credit_account" => "100100365856"
+#   }
+# }
+```
+
+#### Check Previous Days Transaction
+
+```ruby
+response = client.transaction_status.check_previous_days(
+  request_id: "REQ_#{Time.now.to_i}",
+  transaction_id: "test_txn_update23567",
+  transaction_date: "2025-09-18",
+  bene_account_number: "100100365856"
+)
+
+# Response contains array of transaction statuses
+```
+
+## Error Handling
+
+The gem provides specific exception classes for different error scenarios:
+
+```ruby
+begin
+  client.authenticate!
+rescue DkPaymentGateway::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+rescue DkPaymentGateway::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue DkPaymentGateway::InvalidParameterError => e
+  puts "Invalid parameters: #{e.message}"
+  puts "Response code: #{e.response_code}"
+  puts "Response detail: #{e.response_detail}"
+rescue DkPaymentGateway::TransactionError => e
+  puts "Transaction failed: #{e.message}"
+  puts "Response code: #{e.response_code}"
+rescue DkPaymentGateway::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue DkPaymentGateway::SignatureError => e
+  puts "Signature generation failed: #{e.message}"
+rescue DkPaymentGateway::APIError => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Bank Codes Reference
+
+Common bank codes for use with the API:
+
+- `1010` - Bank of Bhutan
+- `1040` - Bhutan National Bank
+- `1060` - Digital Kidu (for intra-bank transactions)
+
+## Merchant Category Codes (MCC)
+
+Refer to ISO 18245 standard for complete list. Common examples:
+
+- `5411` - Grocery Stores, Supermarkets
+- `5812` - Eating Places, Restaurants
+- `5999` - Miscellaneous and Specialty Retail Stores
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+To run tests:
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+

data/SUMMARY.md

@@ -0,0 +1,285 @@
+# DK Payment Gateway Ruby Gem - Summary
+
+## Overview
+
+The **DK Payment Gateway Ruby Gem** is a comprehensive client library for integrating with the Digital Kidu Payment Gateway API. It provides a clean, object-oriented interface for all payment gateway operations.
+
+## Key Features
+
+### 1. **Authentication & Security**
+- OAuth 2.0 token-based authentication
+- RSA signature generation (RS256 algorithm)
+- Automatic request signing with DK-Signature headers
+- Secure credential management
+
+### 2. **Pull Payment Operations**
+- Payment gateway authorization with OTP
+- Debit request processing
+- STAN number generation utility
+- Support for transaction fees
+
+### 3. **Intra-Bank Transactions**
+- Beneficiary account inquiry
+- Fund transfer between DK accounts
+- Real-time account validation
+- Transaction status tracking
+
+### 4. **QR Code Payments**
+- Static QR generation (customer enters amount)
+- Dynamic QR generation (fixed amount)
+- Base64 image handling
+- MCC code support
+
+### 5. **Transaction Status**
+- Current day transaction verification
+- Historical transaction lookup
+- Detailed status information
+
+### 6. **Error Handling**
+- Comprehensive exception hierarchy
+- Detailed error messages
+- Response code mapping
+- Network error handling
+
+### 7. **Utilities**
+- Request ID generation
+- Timestamp formatting
+- Data validation helpers
+- Bank code mapping
+- MCC code reference
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Client Application                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  DkPaymentGateway::Client                    │
+│  ┌──────────────┬──────────────┬──────────────┬──────────┐  │
+│  │ PullPayment  │ IntraTransaction│ QrPayment │  Status  │  │
+│  └──────────────┴──────────────┴──────────────┴──────────┘  │
+│  ┌──────────────┬──────────────┐                            │
+│  │Authentication│  Signature   │                            │
+│  └──────────────┴──────────────┘                            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Faraday HTTP Client                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              DK Payment Gateway API (REST)                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Module Structure
+
+### Core Modules
+
+1. **DkPaymentGateway::Client**
+   - Main entry point
+   - HTTP request handling
+   - Response processing
+
+2. **DkPaymentGateway::Configuration**
+   - Credential management
+   - API endpoint configuration
+   - Timeout settings
+
+3. **DkPaymentGateway::Authentication**
+   - Token fetching
+   - Private key retrieval
+   - Credential validation
+
+4. **DkPaymentGateway::Signature**
+   - RS256 signing
+   - Header generation
+   - Nonce and timestamp management
+
+### Feature Modules
+
+5. **DkPaymentGateway::PullPayment**
+   - Authorization requests
+   - Debit processing
+   - STAN generation
+
+6. **DkPaymentGateway::IntraTransaction**
+   - Account inquiry
+   - Fund transfers
+   - Intra-bank operations
+
+7. **DkPaymentGateway::QrPayment**
+   - QR code generation
+   - Image handling
+   - Static/dynamic QR support
+
+8. **DkPaymentGateway::TransactionStatus**
+   - Status verification
+   - Historical lookups
+   - Transaction tracking
+
+### Support Modules
+
+9. **DkPaymentGateway::Errors**
+   - Exception hierarchy
+   - Error handling
+   - Response mapping
+
+10. **DkPaymentGateway::Utils**
+    - Helper functions
+    - Validation utilities
+    - Reference data
+
+## API Coverage
+
+### Implemented Endpoints
+
+| Endpoint | Method | Purpose | Status |
+|----------|--------|---------|--------|
+| `/v1/auth/token` | POST | Fetch authorization token | ✅ |
+| `/v1/sign/key` | POST | Fetch RSA private key | ✅ |
+| `/v1/account_auth/pull-payment` | POST | Payment authorization | ✅ |
+| `/v1/debit_request/pull-payment` | POST | Debit request | ✅ |
+| `/v1/beneficiary/account_inquiry` | POST | Account inquiry | ✅ |
+| `/v1/initiate/transaction` | POST | Fund transfer | ✅ |
+| `/v1/generate_qr` | POST | QR generation | ✅ |
+| `/v1/transaction/status` | POST | Current day status | ✅ |
+| `/v1/transactions/status` | POST | Historical status | ✅ |
+
+## Dependencies
+
+### Runtime Dependencies
+- **faraday** (~> 2.0) - HTTP client library
+- **jwt** (~> 2.7) - JWT encoding for signatures
+
+### Development Dependencies
+- **rake** (~> 13.0) - Build automation
+- **rspec** (~> 3.0) - Testing framework
+- **webmock** (~> 3.18) - HTTP request stubbing
+- **vcr** (~> 6.1) - HTTP interaction recording
+- **rubocop** (~> 1.21) - Code style checker
+
+## Documentation
+
+### User Documentation
+- **README.md** - Main documentation with installation and basic usage
+- **QUICK_START.md** - 5-minute quick start guide
+- **EXAMPLES.md** - Comprehensive usage examples
+- **API_REFERENCE.md** - Complete API reference
+
+### Developer Documentation
+- **DEVELOPMENT.md** - Development guide and best practices
+- **CHANGELOG.md** - Version history and changes
+
+### Example Code
+- **examples/simple_payment.rb** - Pull payment example
+- **examples/intra_transfer.rb** - Intra-bank transfer example
+- **examples/generate_qr.rb** - QR code generation example
+
+## Testing
+
+### Test Coverage
+- Configuration tests
+- Client initialization tests
+- Error handling tests
+- Mock API responses
+
+### Test Tools
+- RSpec for unit testing
+- WebMock for HTTP stubbing
+- VCR for recording real API interactions
+
+## Security Features
+
+1. **Credential Protection**
+   - Environment variable support
+   - No hardcoded credentials
+   - Sensitive data masking in logs
+
+2. **Request Signing**
+   - RSA-based signatures
+   - Timestamp validation
+   - Nonce for replay protection
+
+3. **HTTPS Support**
+   - Secure communication
+   - Certificate validation
+   - Timeout protection
+
+## Usage Patterns
+
+### Basic Pattern
+```ruby
+# Configure
+DkPaymentGateway.configure { |c| ... }
+
+# Initialize
+client = DkPaymentGateway.client
+
+# Authenticate
+client.authenticate!
+
+# Use features
+client.pull_payment.authorize(...)
+client.intra_transaction.fund_transfer(...)
+client.qr_payment.generate_qr(...)
+```
+
+### Error Handling Pattern
+```ruby
+begin
+  result = client.pull_payment.authorize(params)
+rescue DkPaymentGateway::TransactionError => e
+  # Handle transaction errors
+rescue DkPaymentGateway::Error => e
+  # Handle general errors
+end
+```
+
+## Best Practices
+
+1. **Always authenticate before operations**
+2. **Use environment variables for credentials**
+3. **Implement proper error handling**
+4. **Generate unique request IDs**
+5. **Log operations for audit trail**
+6. **Validate input before API calls**
+7. **Use utilities for common tasks**
+
+## Future Enhancements
+
+Potential areas for expansion:
+- Webhook support for async notifications
+- Batch payment processing
+- Recurring payment support
+- Enhanced logging and monitoring
+- Rate limiting handling
+- Retry mechanisms
+- Caching for frequently accessed data
+
+## Support & Contribution
+
+- GitHub repository for issues and PRs
+- Comprehensive documentation
+- Example applications
+- Active maintenance
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Version
+
+Current version: **0.1.0**
+
+---
+
+**Created:** October 31, 2025  
+**Last Updated:** October 31, 2025  
+**Status:** Production Ready
+

data/dk_payment_gateway.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/dk_payment_gateway/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "dk_payment_gateway"
+  spec.version = DkPaymentGateway::VERSION
+  spec.authors = ["Tashi Dendup"]
+  spec.email = ["tashii.dendupp@gmail.com"]
+
+  spec.summary = "Ruby client for DK Payment Gateway API"
+  spec.description = "A Ruby gem for integrating with Digital Kidu Payment Gateway API, supporting pull payments, intra-bank transactions, QR generation, and transaction status verification."
+  spec.homepage = "https://github.com/dcplbt/dk_payment_gateway"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/dcplbt/dk_payment_gateway"
+  spec.metadata["changelog_uri"] = "https://github.com/dcplbt/dk_payment_gateway/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "jwt", "~> 2.7"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency "vcr", "~> 6.1"
+end