dk_payment_gateway 1.0.0

data/examples/README.md

@@ -0,0 +1,199 @@
+# DK Payment Gateway - Example Applications
+
+This directory contains example applications demonstrating how to use the DK Payment Gateway gem.
+
+## Prerequisites
+
+Before running these examples, make sure you have:
+
+1. Installed the gem:
+   ```bash
+   gem install dk_payment_gateway
+   ```
+
+2. Set up your environment variables in a `.env` file:
+   ```bash
+   DK_BASE_URL=http://internal-gateway.uat.digitalkidu.bt/api/dkpg
+   DK_API_KEY=your_api_key
+   DK_USERNAME=your_username
+   DK_PASSWORD=your_password
+   DK_CLIENT_ID=your_client_id
+   DK_CLIENT_SECRET=your_client_secret
+   DK_SOURCE_APP=SRC_AVS_0201
+   ```
+
+3. Install dotenv gem (optional, for loading .env files):
+   ```bash
+   gem install dotenv
+   ```
+
+## Examples
+
+### 1. Simple Payment (`simple_payment.rb`)
+
+Demonstrates a complete pull payment flow:
+- Authentication
+- Payment authorization (sends OTP)
+- OTP collection from user
+- Payment completion with OTP
+
+**Run:**
+```bash
+ruby examples/simple_payment.rb
+```
+
+**What it does:**
+1. Authenticates with the API
+2. Initiates a payment authorization for BTN 100.00
+3. Prompts for OTP
+4. Completes the payment
+
+### 2. Intra-Bank Transfer (`intra_transfer.rb`)
+
+Demonstrates transferring funds between DK accounts:
+- Account verification
+- Fund transfer
+- Transaction confirmation
+
+**Run:**
+```bash
+ruby examples/intra_transfer.rb
+```
+
+**What it does:**
+1. Authenticates with the API
+2. Verifies beneficiary account
+3. Asks for confirmation
+4. Executes the transfer
+
+### 3. QR Code Generation (`generate_qr.rb`)
+
+Demonstrates generating QR codes for payments:
+- Static QR (customer enters amount)
+- Dynamic QR (fixed amount)
+- QR image saving
+
+**Run:**
+```bash
+ruby examples/generate_qr.rb
+```
+
+**What it does:**
+1. Authenticates with the API
+2. Asks user to choose QR type
+3. Generates QR code
+4. Saves QR image to file
+
+## Customizing Examples
+
+### Changing Payment Amounts
+
+Edit the amount variables in each script:
+
+```ruby
+# In simple_payment.rb
+amount = 100.00  # Change this
+fee = 5.00       # Change this
+
+# In intra_transfer.rb
+amount = 500.00  # Change this
+```
+
+### Changing Account Numbers
+
+Update the account numbers to match your test accounts:
+
+```ruby
+# Beneficiary account
+account_number: "110158212197"  # Change this
+
+# Remitter account
+remitter_account_number: "770182571"  # Change this
+```
+
+### Changing Bank Codes
+
+Use different bank codes as needed:
+
+```ruby
+remitter_bank_id: "1040"  # 1010, 1040, 1060, etc.
+```
+
+## Error Handling
+
+All examples include error handling. If you encounter errors:
+
+1. **Authentication Error**
+   - Check your credentials in .env file
+   - Verify API endpoint is accessible
+
+2. **Transaction Error**
+   - Check account numbers are valid
+   - Verify sufficient balance
+   - Ensure OTP is correct
+
+3. **Network Error**
+   - Check internet connection
+   - Verify API endpoint URL
+
+## Testing in Development
+
+For testing without affecting real accounts:
+
+1. Use the UAT (User Acceptance Testing) environment
+2. Use test account numbers provided by DK
+3. Use small amounts for testing
+
+## Creating Your Own Examples
+
+Use these examples as templates:
+
+```ruby
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'dk_payment_gateway'
+
+# Configure
+DkPaymentGateway.configure do |config|
+  config.base_url = ENV['DK_BASE_URL']
+  config.api_key = ENV['DK_API_KEY']
+  # ... other config
+end
+
+# Your code here
+client = DkPaymentGateway.client
+client.authenticate!
+
+# Use the client
+# ...
+```
+
+## Additional Resources
+
+- [Main README](../README.md) - Complete documentation
+- [Quick Start Guide](../QUICK_START.md) - Get started in 5 minutes
+- [API Reference](../API_REFERENCE.md) - Detailed API documentation
+- [Examples Guide](../EXAMPLES.md) - More usage examples
+
+## Support
+
+If you encounter issues with these examples:
+
+1. Check the error message
+2. Review the documentation
+3. Verify your credentials
+4. Check account numbers and amounts
+5. Ensure you're using the correct environment (UAT/Production)
+
+## Security Note
+
+⚠️ **Never commit your `.env` file or credentials to version control!**
+
+Add to your `.gitignore`:
+```
+.env
+.env.*
+*.pem
+*.key
+```
+

data/examples/generate_qr.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# QR code generation example using DK Payment Gateway
+# This demonstrates generating both static and dynamic QR codes
+
+require 'bundler/setup'
+require 'dk_payment_gateway'
+
+# Configure the client
+DkPaymentGateway.configure do |config|
+  config.base_url = ENV['DK_BASE_URL'] || "http://internal-gateway.uat.digitalkidu.bt/api/dkpg"
+  config.api_key = ENV['DK_API_KEY']
+  config.username = ENV['DK_USERNAME']
+  config.password = ENV['DK_PASSWORD']
+  config.client_id = ENV['DK_CLIENT_ID']
+  config.client_secret = ENV['DK_CLIENT_SECRET']
+  config.source_app = ENV['DK_SOURCE_APP'] || "SRC_AVS_0201"
+end
+
+def main
+  puts "=== DK Payment Gateway - QR Code Generation Example ==="
+  puts
+
+  # Initialize client
+  client = DkPaymentGateway.client
+  
+  # Authenticate
+  puts "Authenticating..."
+  client.authenticate!
+  puts "✓ Authentication successful"
+  puts
+
+  # Merchant details
+  merchant_account = "100100148337"
+  
+  puts "Select QR type:"
+  puts "1. Static QR (customer enters amount)"
+  puts "2. Dynamic QR (fixed amount)"
+  print "Choice (1 or 2): "
+  choice = gets.chomp
+  puts
+
+  begin
+    case choice
+    when "1"
+      generate_static_qr(client, merchant_account)
+    when "2"
+      generate_dynamic_qr(client, merchant_account)
+    else
+      puts "Invalid choice"
+    end
+  rescue DkPaymentGateway::Error => e
+    puts "✗ Error: #{e.message}"
+  end
+end
+
+def generate_static_qr(client, merchant_account)
+  puts "Generating Static QR Code..."
+  puts "  Merchant Account: #{merchant_account}"
+  puts "  Amount: Customer will enter"
+  puts
+
+  response = client.qr_payment.generate_qr(
+    request_id: DkPaymentGateway::Utils.generate_request_id("QR"),
+    currency: "BTN",
+    bene_account_number: merchant_account,
+    amount: 0, # 0 = static QR
+    mcc_code: "5411", # Grocery store
+    remarks: "Payment to merchant"
+  )
+
+  filename = "static_qr_#{Time.now.to_i}.png"
+  client.qr_payment.save_qr_image(response['image'], filename)
+  
+  puts "✓ Static QR code generated successfully!"
+  puts "  Saved to: #{filename}"
+  puts "  Customers can scan this QR and enter any amount"
+end
+
+def generate_dynamic_qr(client, merchant_account)
+  print "Enter amount (BTN): "
+  amount = gets.chomp.to_f
+  puts
+
+  puts "Generating Dynamic QR Code..."
+  puts "  Merchant Account: #{merchant_account}"
+  puts "  Amount: BTN #{DkPaymentGateway::Utils.format_amount(amount)}"
+  puts
+
+  response = client.qr_payment.generate_qr(
+    request_id: DkPaymentGateway::Utils.generate_request_id("QR"),
+    currency: "BTN",
+    bene_account_number: merchant_account,
+    amount: amount,
+    mcc_code: "5812", # Restaurant
+    remarks: "Invoice payment"
+  )
+
+  filename = "dynamic_qr_#{amount.to_i}_#{Time.now.to_i}.png"
+  client.qr_payment.save_qr_image(response['image'], filename)
+  
+  puts "✓ Dynamic QR code generated successfully!"
+  puts "  Saved to: #{filename}"
+  puts "  Amount is fixed at BTN #{DkPaymentGateway::Utils.format_amount(amount)}"
+end
+
+# Run the example
+main if __FILE__ == $PROGRAM_NAME
+

data/examples/intra_transfer.rb

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Intra-bank transfer example using DK Payment Gateway
+# This demonstrates transferring funds between DK accounts
+
+require 'bundler/setup'
+require 'dk_payment_gateway'
+
+# Configure the client
+DkPaymentGateway.configure do |config|
+  config.base_url = ENV['DK_BASE_URL'] || "http://internal-gateway.uat.digitalkidu.bt/api/dkpg"
+  config.api_key = ENV['DK_API_KEY']
+  config.username = ENV['DK_USERNAME']
+  config.password = ENV['DK_PASSWORD']
+  config.client_id = ENV['DK_CLIENT_ID']
+  config.client_secret = ENV['DK_CLIENT_SECRET']
+  config.source_app = ENV['DK_SOURCE_APP'] || "SRC_AVS_0201"
+end
+
+def main
+  puts "=== DK Payment Gateway - Intra-Bank Transfer Example ==="
+  puts
+
+  # Initialize client
+  client = DkPaymentGateway.client
+  
+  # Authenticate
+  puts "Authenticating..."
+  client.authenticate!
+  puts "✓ Authentication successful"
+  puts
+
+  # Transfer details
+  source_account = "100100365856"
+  beneficiary_account = "100100148337"
+  amount = 500.00
+  
+  puts "Transfer Details:"
+  puts "  From: #{source_account}"
+  puts "  To: #{beneficiary_account}"
+  puts "  Amount: BTN #{amount}"
+  puts
+
+  begin
+    # Step 1: Verify beneficiary account
+    puts "Step 1: Verifying beneficiary account..."
+    
+    inquiry_response = client.intra_transaction.account_inquiry(
+      request_id: DkPaymentGateway::Utils.generate_request_id("INQ"),
+      amount: amount,
+      currency: "BTN",
+      bene_bank_code: "1060",
+      bene_account_number: beneficiary_account,
+      source_account_number: source_account
+    )
+    
+    puts "✓ Account verified"
+    puts "  Inquiry ID: #{inquiry_response['inquiry_id']}"
+    puts "  Beneficiary Name: #{inquiry_response['account_name']}"
+    puts
+
+    # Step 2: Confirm transfer
+    print "Proceed with transfer? (yes/no): "
+    confirmation = gets.chomp.downcase
+    
+    unless confirmation == 'yes' || confirmation == 'y'
+      puts "Transfer cancelled"
+      return
+    end
+    puts
+
+    # Step 3: Execute transfer
+    puts "Step 2: Executing transfer..."
+    
+    transfer_response = client.intra_transaction.fund_transfer(
+      request_id: DkPaymentGateway::Utils.generate_request_id("TXN"),
+      inquiry_id: inquiry_response['inquiry_id'],
+      transaction_datetime: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+      transaction_amount: amount,
+      currency: "BTN",
+      payment_type: "INTRA",
+      source_account_number: source_account,
+      bene_cust_name: inquiry_response['account_name'],
+      bene_account_number: beneficiary_account,
+      bene_bank_code: "1060",
+      narration: "Test transfer"
+    )
+    
+    puts "✓ Transfer completed successfully!"
+    puts "  Transaction Status ID: #{transfer_response['txn_status_id']}"
+    puts
+
+    # Step 4: Verify transaction status
+    puts "Step 3: Verifying transaction status..."
+    
+    # Wait a moment for transaction to process
+    sleep 2
+    
+    # Note: You would use the actual transaction_id returned by the system
+    # This is just an example
+    puts "✓ Transfer processed"
+    
+  rescue DkPaymentGateway::TransactionError => e
+    puts "✗ Transaction error: #{e.message}"
+    puts "  Error code: #{e.response_code}"
+  rescue DkPaymentGateway::Error => e
+    puts "✗ Error: #{e.message}"
+  end
+end
+
+# Run the example
+main if __FILE__ == $PROGRAM_NAME
+

data/examples/simple_payment.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Simple payment example using DK Payment Gateway
+# This demonstrates a basic pull payment flow
+
+require 'bundler/setup'
+require 'dk_payment_gateway'
+
+# Configure the client
+DkPaymentGateway.configure do |config|
+  config.base_url = ENV['DK_BASE_URL'] || 'https://internal-gateway.uat.digitalkidu.bt'
+  config.api_key = ENV['DK_API_KEY']
+  config.username = ENV['DK_USERNAME']
+  config.password = ENV['DK_PASSWORD']
+  config.client_id = ENV['DK_CLIENT_ID']
+  config.client_secret = ENV['DK_CLIENT_SECRET']
+  config.source_app = ENV['DK_SOURCE_APP'] || 'SRC_AVS_0201'
+end
+
+def main
+  puts '=== DK Payment Gateway - Simple Payment Example ==='
+  puts
+
+  # Initialize client
+  client = DkPaymentGateway.client
+
+  # Authenticate
+  puts 'Authenticating...'
+  client.authenticate!
+  puts '✓ Authentication successful'
+  puts
+
+  # Payment details
+  amount = 100.00
+  fee = 5.00
+
+  puts 'Payment Details:'
+  puts "  Amount: BTN #{amount}"
+  puts "  Fee: BTN #{fee}"
+  puts "  Total: BTN #{amount + fee}"
+  puts
+
+  # Step 1: Request authorization
+  puts 'Step 1: Requesting payment authorization...'
+
+  stan = DkPaymentGateway::PullPayment.generate_stan('0201')
+
+  begin
+    auth_response = client.pull_payment.authorize(
+      transaction_datetime: Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ'),
+      stan_number: stan,
+      transaction_amount: amount,
+      transaction_fee: fee,
+      payment_desc: 'Test payment - Order #TEST001',
+      account_number: '110158212197',
+      account_name: 'Test Merchant',
+      phone_number: '17811440',
+      remitter_account_number: '770182571',
+      remitter_account_name: 'Test Customer',
+      remitter_bank_id: '1040'
+    )
+
+    puts '✓ Authorization successful'
+    puts "  Transaction ID: #{auth_response['bfs_txn_id']}"
+    puts "  STAN: #{auth_response['stan_number']}"
+    puts
+
+    # Step 2: Get OTP from user
+    puts "Step 2: OTP has been sent to customer's phone"
+    print 'Enter OTP: '
+    otp = gets.chomp
+    puts
+
+    # Step 3: Complete payment
+    puts 'Step 3: Completing payment with OTP...'
+
+    debit_response = client.pull_payment.debit(
+      request_id: DkPaymentGateway::Utils.generate_request_id('PAY'),
+      bfs_txn_id: auth_response['bfs_txn_id'],
+      bfs_remitter_otp: otp
+    )
+
+    if debit_response['code'] == '00'
+      puts '✓ Payment completed successfully!'
+      puts "  Transaction ID: #{debit_response['bfs_txn_id']}"
+      puts "  Status: #{debit_response['description']}"
+    else
+      puts '✗ Payment failed'
+      puts "  Code: #{debit_response['code']}"
+      puts "  Description: #{debit_response['description']}"
+    end
+  rescue DkPaymentGateway::TransactionError => e
+    puts "✗ Transaction error: #{e.message}"
+    puts "  Error code: #{e.response_code}"
+  rescue DkPaymentGateway::Error => e
+    puts "✗ Error: #{e.message}"
+  end
+end
+
+# Run the example
+main if __FILE__ == $PROGRAM_NAME

data/lib/dk_payment_gateway/authentication.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "uri"
+require "securerandom"
+
+module DkPaymentGateway
+  class Authentication
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Fetch authorization token
+    # Returns the access token string
+    def fetch_token
+      response = client.post(
+        "/v1/auth/token",
+        body: token_request_body,
+        headers: token_request_headers,
+        skip_auth: true
+      )
+
+      validate_token_response!(response)
+      
+      response["response_data"]["access_token"]
+    rescue => e
+      raise AuthenticationError, "Failed to fetch token: #{e.message}"
+    end
+
+    # Fetch RSA private key for signing requests
+    # Returns the private key as a string
+    def fetch_private_key
+      raise AuthenticationError, "Access token required to fetch private key" unless client.access_token
+
+      request_id = generate_request_id
+      
+      response = client.post(
+        "/v1/sign/key",
+        body: {
+          request_id: request_id,
+          source_app: client.config.source_app
+        },
+        skip_auth: false
+      )
+
+      # The response is plain text containing the private key
+      if response.is_a?(String) && response.include?("BEGIN RSA PRIVATE KEY")
+        response
+      elsif response.is_a?(Hash) && response["response_code"] == "3001"
+        raise AuthenticationError, "Private key not found: #{response['response_detail']}"
+      else
+        raise AuthenticationError, "Invalid private key response"
+      end
+    rescue DkPaymentGateway::Error => e
+      raise
+    rescue => e
+      raise AuthenticationError, "Failed to fetch private key: #{e.message}"
+    end
+
+    private
+
+    def token_request_body
+      params = {
+        username: client.config.username,
+        password: client.config.password,
+        client_id: client.config.client_id,
+        client_secret: client.config.client_secret,
+        grant_type: "password",
+        scopes: "keys:read",
+        source_app: client.config.source_app,
+        request_id: generate_request_id
+      }
+
+      # Convert to URL-encoded format
+      URI.encode_www_form(params)
+    end
+
+    def token_request_headers
+      {
+        "Content-Type" => "application/x-www-form-urlencoded",
+        "X-gravitee-api-key" => client.config.api_key
+      }
+    end
+
+    def validate_token_response!(response)
+      unless response.is_a?(Hash) && response["response_code"] == "0000"
+        error_detail = response["response_detail"] || response["response_message"] || "Unknown error"
+        raise AuthenticationError, "Token request failed: #{error_detail}"
+      end
+
+      unless response["response_data"] && response["response_data"]["access_token"]
+        raise AuthenticationError, "No access token in response"
+      end
+    end
+
+    def generate_request_id
+      "#{Time.now.to_i}-#{SecureRandom.hex(8)}"
+    end
+  end
+end
+