payangel 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78d69482a78e2db741b045780cf31cb172f1f01e340d3742c35cff43915efc25
+  data.tar.gz: 5c00884d15bf2553ac5de0464edc868fe6a301c3287a322ac7d94d6447d1229f
+SHA512:
+  metadata.gz: 2233e1a2dd73d4637c665b69a503ea6054752b7a2731a127f7ccc3d74ba15a8898ce017906cca83b7e39c54f768f77f570c511cf60e46cdf854ed39b838a896e
+  data.tar.gz: 88332384adef8033bf82e174bb64fb91799112fc7b93717cc81a50ba90c6b13910de8d9bde1580ac23a20d4f28f555e5e3871ca52610649d162048b27e4edf75

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Charles Agyemang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,549 @@
+[![Gem Version](https://badge.fury.io/rb/payangel.svg)](https://rubygems.org/gems/payangel)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%202.7-red.svg)](https://www.ruby-lang.org)
+[![GitHub](https://img.shields.io/badge/GitHub-source-black.svg)](https://github.com/charlesagyemang/payangel-ruby-gem)
+
+# PayAngel Ruby SDK
+
+Official Ruby SDK for the [PayAngel](https://payangel.com) payments API — send and collect money across Africa (Ghana, Nigeria, Kenya, South Africa).
+
+**Zero runtime dependencies. Works with Ruby 2.7+.**
+
+Built for developers familiar with Stripe, Paystack, and Flutterwave — the API surface will feel immediately familiar.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Environments](#environments)
+- [Disbursement](#disbursement)
+- [Collection](#collection)
+- [Webhooks](#webhooks)
+- [Error Handling](#error-handling)
+- [Normalised Response](#normalised-response)
+- [Important Notes](#important-notes)
+- [Known Limitations](#known-limitations)
+- [License](#license)
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "payangel"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install payangel
+```
+
+---
+
+## Quick Start
+
+```ruby
+require "payangel"
+
+client = PayAngel::Client.new(
+  public_key: "your_public_key",
+  secret_key: "your_secret_key",
+  env: "production"
+)
+
+# Check your wallet balance
+balance = client.disbursement.balance
+puts balance.data
+# => { "wallets" => [{ "currency" => "USD", "balance" => "1000.00" }] }
+
+# Get available banks in Ghana
+banks = client.disbursement.bank_codes(country: "GH")
+banks.data["banks"].each { |b| puts "#{b['payangelCode']} — #{b['name']}" }
+
+# Send money to a bank account
+result = client.disbursement.send_money(
+  transaction_id: "PAY-001",
+  sender_first_name: "John",
+  sender_last_name: "Doe",
+  country_from: "GH",
+  country_to: "GH",
+  sending_currency: "GHS",
+  receiving_currency: "GHS",
+  destination_amount: 100,
+  beneficiary_first_name: "Jane",
+  beneficiary_last_name: "Mensah",
+  transfer_type: "bank",
+  bank_account_number: "1234567890",
+  bank_code: "170100",
+  transfer_reason: "Family Support",
+  customer_ref: "REF-001",
+  callback_url: "https://yourserver.com/webhooks/payangel"
+)
+
+puts result.success        # => true
+puts result.transaction_id # => "PAY-001"
+puts result.reference_id   # => "STA-100000000143"
+puts result.status         # => "PENDING"
+puts result.amount         # => 100
+puts result.fee            # => 0
+```
+
+---
+
+## Authentication
+
+The SDK uses HTTP Basic Auth with your PayAngel API keys from [business.payangel.com](https://business.payangel.com).
+
+### Option A: Pass keys directly
+
+```ruby
+client = PayAngel::Client.new(
+  public_key: "your_public_key",
+  secret_key: "your_secret_key",
+  env: "production",
+  timeout: 30         # optional, in seconds, defaults to 30
+)
+```
+
+### Option B: Use environment variables
+
+```bash
+export PAYANGEL_PUBLIC_KEY=your_public_key
+export PAYANGEL_SECRET_KEY=your_secret_key
+export PAYANGEL_ENV=production
+```
+
+```ruby
+client = PayAngel::Client.new  # reads from env vars
+```
+
+### Option C: Global configuration
+
+```ruby
+PayAngel.configure do |config|
+  config.public_key = "your_public_key"
+  config.secret_key = "your_secret_key"
+  config.env = "production"
+end
+
+client = PayAngel::Client.new  # uses global config
+```
+
+### Config resolution priority
+
+1. Explicit constructor arguments
+2. Global configuration (`PayAngel.configure`)
+3. Environment variables (`PAYANGEL_PUBLIC_KEY`, `PAYANGEL_SECRET_KEY`, `PAYANGEL_ENV`)
+4. Defaults (`"production"` for env, `30` for timeout)
+
+An `AuthenticationError` is raised at instantiation if no keys are found.
+
+### IP Whitelisting
+
+PayAngel requires your server IP to be whitelisted. If you receive error code `E0014-098`, add your server's public IP to the whitelist at [business.payangel.com](https://business.payangel.com) under your channel settings.
+
+---
+
+## Environments
+
+| Environment | Domain |
+|---|---|
+| Sandbox | `https://payconnect.payangel.org` |
+| Production | `https://payconnect.payangel.com` |
+
+```ruby
+# Sandbox
+client = PayAngel::Client.new(env: "sandbox", ...)
+
+# Production (default)
+client = PayAngel::Client.new(env: "production", ...)
+```
+
+---
+
+## Disbursement
+
+### Send Money (Bank Transfer)
+
+```ruby
+result = client.disbursement.send_money(
+  transaction_id: "PAY-BANK-001",
+  sender_first_name: "John",
+  sender_last_name: "Doe",
+  country_from: "GH",
+  country_to: "GH",
+  sending_currency: "GHS",
+  receiving_currency: "GHS",
+  destination_amount: 100,
+  beneficiary_first_name: "Jane",
+  beneficiary_last_name: "Mensah",
+  transfer_type: "bank",
+  bank_account_number: "1775702701014",
+  bank_name: "FIRST ATLANTIC BANK",
+  bank_branch: "EAST LEGON",
+  bank_code: "170100",
+  transfer_reason: "Family Support",
+  customer_ref: "REF-001",
+  callback_url: "https://yourserver.com/webhooks/payangel"
+)
+```
+
+#### Optional sender fields
+
+```ruby
+{
+  sender_middlename: "Michael",
+  sender_phone: "+1234567890",
+  sender_address: "123 Main St",
+  sender_city: "New York",
+  sender_nationality: "US",
+  sender_id_expiry: "2028-12-31",
+  source_of_income: "Employment",
+  beneficiary_middle_name: "Akua",
+  recipient_nationality: "GH",
+  receiver_dob: "1990-01-15",
+  purpose_details: "Monthly allowance",
+}
+```
+
+### Send Money (Mobile Money)
+
+```ruby
+result = client.disbursement.send_money(
+  transaction_id: "PAY-MOMO-001",
+  sender_first_name: "John",
+  sender_last_name: "Doe",
+  country_from: "GH",
+  country_to: "GH",
+  sending_currency: "GHS",
+  receiving_currency: "GHS",
+  destination_amount: 50,
+  beneficiary_first_name: "Kwame",
+  beneficiary_last_name: "Asante",
+  transfer_type: "mobile",
+  mobile_network: "MTN",         # accepts any casing: "mtn", "MTN", "Mtn"
+  mobile_number: "0551234567",
+  transfer_reason: "Gift",
+  customer_ref: "REF-002",
+  callback_url: "https://yourserver.com/webhooks/payangel"
+)
+```
+
+#### Supported mobile networks
+
+| Input (any casing) | Disbursement sends | Collection sends |
+|---|---|---|
+| `"mtn"` / `"MTN"` | `"MTN"` | `"mtn"` |
+| `"telecel"` / `"vodafone"` | `"Telecel"` | `"telecel"` |
+| `"airteltigo"` / `"at"` | `"AirtelTigo"` | `"at"` |
+
+The SDK normalises `mobile_network` automatically.
+
+### Query Transaction
+
+```ruby
+status = client.disbursement.query("PAY-BANK-001")
+
+puts status.status         # => "SUCCESS"
+puts status.transaction_id # => "PAY-BANK-001"
+puts status.amount         # => 100
+puts status.fee            # => 0
+```
+
+### Account Balance
+
+```ruby
+balance = client.disbursement.balance
+puts balance.data
+# => { "wallets" => [{ "currency" => "USD", "balance" => "1000.00" }] }
+```
+
+### Bank Codes
+
+```ruby
+codes = client.disbursement.bank_codes(country: "GH")
+
+# Banks
+codes.data["banks"].each do |bank|
+  puts "#{bank['payangelCode']} — #{bank['name']}"
+end
+
+# Mobile providers
+codes.data["mobile"].each do |provider|
+  puts "#{provider['payangelCode']} — #{provider['name']}"
+end
+```
+
+### Name Check
+
+```ruby
+check = client.disbursement.name_check(
+  country: "GH",
+  account_number: "1775702701014",
+  payangel_code: "170100",
+  account_type: "bank"
+)
+
+puts check.success # => true
+puts check.name    # => "JANE MENSAH"
+```
+
+---
+
+## Collection
+
+### Mobile Money Collection
+
+```ruby
+result = client.collection.mobile_money(
+  mobile_network: "mtn",
+  ip_address: "154.160.2.56",
+  transaction_id: "COLL-MOMO-001",
+  country: "GH",
+  amount: 5,
+  customer_account: "233541348180",  # must include country code
+  currency: "GHS",
+  item_description: "Order #1042",
+  callback_url: "https://yourserver.com/webhooks/payangel"
+)
+
+puts result.success        # => true
+puts result.transaction_id # => "COLL-MOMO-001"
+puts result.status         # => "PENDING"
+puts result.amount         # => 5
+puts result.currency       # => "GHS"
+```
+
+### Card Collection
+
+```ruby
+result = client.collection.card(
+  transaction_id: "COLL-CARD-001",
+  country: "GH",
+  customer_account: "customer@example.com",
+  currency: "GHS",
+  amount: 100,
+  item_description: "Premium subscription",
+  redirect_url: "https://yoursite.com/payment/complete"
+)
+```
+
+### Collection Status
+
+```ruby
+status = client.collection.status("COLL-MOMO-001")
+puts status.status         # => "SUCCESS" or "PENDING"
+```
+
+---
+
+## Webhooks
+
+Verify webhook signatures using HMAC-SHA256 with timing-safe comparison.
+
+### Rails example
+
+```ruby
+# config/routes.rb
+post "/webhooks/payangel", to: "webhooks#payangel"
+
+# app/controllers/webhooks_controller.rb
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token, only: :payangel
+
+  def payangel
+    payload = request.body.read
+    signature = request.headers["X-PayAngel-Signature"]
+
+    begin
+      event = PayAngel::Webhook.verify(
+        payload: payload,
+        signature: signature,
+        secret: ENV["PAYANGEL_WEBHOOK_SECRET"]
+      )
+
+      case event.type
+      when "disbursement.completed"
+        handle_completed(event.data)
+      when "disbursement.failed"
+        handle_failed(event.data)
+      end
+
+      head :ok
+    rescue PayAngel::WebhookSignatureError
+      head :unauthorized
+    end
+  end
+
+  private
+
+  def handle_completed(data)
+    # data[:transaction_id], data[:amount], data[:currency], etc.
+  end
+
+  def handle_failed(data)
+    # data[:failure_reason]
+  end
+end
+```
+
+### Sinatra example
+
+```ruby
+post "/webhooks/payangel" do
+  payload = request.body.read
+  signature = request.env["HTTP_X_PAYANGEL_SIGNATURE"]
+
+  begin
+    event = PayAngel::Webhook.verify(
+      payload: payload,
+      signature: signature,
+      secret: ENV["PAYANGEL_WEBHOOK_SECRET"]
+    )
+    # Handle event...
+    status 200
+  rescue PayAngel::WebhookSignatureError
+    status 401
+  end
+end
+```
+
+### Webhook event types
+
+| Event | Description |
+|---|---|
+| `disbursement.pending` | Transaction created, awaiting processing |
+| `disbursement.processing` | Transaction is being processed |
+| `disbursement.completed` | Transaction completed successfully |
+| `disbursement.failed` | Transaction failed |
+| `disbursement.cancelled` | Transaction was cancelled |
+
+---
+
+## Error Handling
+
+All errors inherit from `PayAngel::Error` and include structured metadata.
+
+```ruby
+begin
+  client.disbursement.send_money(...)
+rescue PayAngel::AuthenticationError => e
+  # 401/403 or E0014-098 (IP whitelist)
+  puts e.message
+  puts e.code
+rescue PayAngel::InvalidRequestError => e
+  # 400/422 — validation errors
+  puts e.message
+  puts e.fields  # => [{ "field" => "...", "message" => "..." }]
+rescue PayAngel::RateLimitError => e
+  # 429 — SDK auto-retries 3x with exponential backoff
+  puts "Rate limited after retries"
+rescue PayAngel::TransactionError => e
+  # Business logic error (E0016-xxx)
+  puts e.code, e.message
+rescue PayAngel::ServiceUnavailableError => e
+  # 500/503
+  puts "Service down"
+rescue PayAngel::Error => e
+  # Catch-all
+  puts e.http_status, e.message, e.raw
+end
+```
+
+### Error properties
+
+| Property | Type | Description |
+|---|---|---|
+| `message` | `String` | Human-readable description |
+| `http_status` | `Integer` | HTTP status code (0 for non-HTTP errors) |
+| `code` | `String` or `nil` | PayAngel error code (e.g. `"E0016-007"`) |
+| `fields` | `Array<Hash>` | Per-field validation errors |
+| `raw` | `Hash` or `nil` | Original unmodified API response |
+
+### Automatic retry
+
+The SDK automatically retries on `429 Too Many Requests` with exponential backoff:
+
+- Attempt 1: wait ~1s
+- Attempt 2: wait ~2s
+- Attempt 3: wait ~4s
+- Attempt 4: raise `RateLimitError`
+
+---
+
+## Normalised Response
+
+Every method returns a `PayAngel::Response` with consistent attributes:
+
+```ruby
+response.success        # Boolean
+response.transaction_id # String or nil
+response.reference_id   # String or nil
+response.status         # String or nil ("PENDING", "SUCCESS", "FAILED", etc.)
+response.amount         # Numeric or nil
+response.fee            # Numeric or nil
+response.total          # Numeric or nil
+response.currency       # String or nil
+response.created_at     # String or nil
+response.data           # Hash or nil — typed payload specific to the method
+response.raw            # Hash — original API response, unmodified
+```
+
+---
+
+## Important Notes
+
+### `destination_amount` is what the recipient gets
+
+`destination_amount` is the amount the **recipient receives**. Your wallet debit = destination_amount + fee + FX spread.
+
+### `bank_code` = `payangel_code`
+
+The `bank_code` param in `send_money` expects the `payangelCode` from `bank_codes`. Different names, same value.
+
+### `customer_account` format for collection
+
+Must include the country code:
+
+```ruby
+customer_account: "233541348180"  # 233 = Ghana
+# NOT "0541348180"
+```
+
+### `callback_url` is required
+
+Both disbursement and collection require a callback URL for webhook notifications.
+
+---
+
+## Known Limitations
+
+| # | Question | Current SDK behaviour |
+|---|----------|----------------------|
+| 1 | Does Collection use `Basic` or `Bearer` auth? | Uses `Basic`. One-line change if Bearer needed. |
+| 2 | Does per-request `callback_url` override portal URL? | Assumed yes. |
+| 3 | Does `Retry-After` header exist on 429? | SDK uses fixed exponential backoff. |
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/charlesagyemang/payangel-ruby-gem).
+
+---
+
+## License
+
+MIT — see [LICENSE.txt](https://github.com/charlesagyemang/payangel-ruby-gem/blob/main/LICENSE.txt).

data/lib/payangel/client.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module PayAngel
+  # Main client class. Instantiate with API keys and access resources.
+  #
+  # @example Explicit keys
+  #   client = PayAngel::Client.new(
+  #     public_key: "pk_live_...",
+  #     secret_key: "sk_live_...",
+  #     env: "production"
+  #   )
+  #
+  # @example Environment variables
+  #   # Set PAYANGEL_PUBLIC_KEY, PAYANGEL_SECRET_KEY, PAYANGEL_ENV
+  #   client = PayAngel::Client.new
+  #
+  # @example Access resources
+  #   client.disbursement.send_money(...)
+  #   client.disbursement.query(transaction_id)
+  #   client.disbursement.balance
+  #   client.collection.mobile_money(...)
+  #   client.collection.status(transaction_id)
+  class Client
+    attr_reader :config
+
+    # @param public_key [String, nil] your PayAngel public key (falls back to PAYANGEL_PUBLIC_KEY)
+    # @param secret_key [String, nil] your PayAngel secret key (falls back to PAYANGEL_SECRET_KEY)
+    # @param env [String, nil] "sandbox" or "production" (falls back to PAYANGEL_ENV, default "production")
+    # @param timeout [Integer, nil] request timeout in seconds (default 30)
+    # @raise [PayAngel::AuthenticationError] if keys are missing
+    def initialize(public_key: nil, secret_key: nil, env: nil, timeout: nil)
+      @config = Configuration.new(
+        public_key: public_key,
+        secret_key: secret_key,
+        env: env,
+        timeout: timeout
+      )
+      @config.validate!
+      @http = HttpClient.new(@config)
+    end
+
+    # @return [PayAngel::Resources::Disbursement]
+    def disbursement
+      @disbursement ||= Resources::Disbursement.new(@http)
+    end
+
+    # @return [PayAngel::Resources::Collection]
+    def collection
+      @collection ||= Resources::Collection.new(@http)
+    end
+  end
+end

data/lib/payangel/configuration.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PayAngel
+  # Holds resolved configuration for a PayAngel client.
+  #
+  # Resolution priority:
+  #   1. Explicit value passed to constructor / configure block
+  #   2. Environment variable
+  #   3. Default
+  class Configuration
+    attr_accessor :public_key, :secret_key, :env, :timeout
+
+    ENVIRONMENTS = {
+      "sandbox"    => "https://payconnect.payangel.org",
+      "production" => "https://payconnect.payangel.com"
+    }.freeze
+
+    def initialize(public_key: nil, secret_key: nil, env: nil, timeout: nil)
+      @public_key = public_key || ENV["PAYANGEL_PUBLIC_KEY"]
+      @secret_key = secret_key || ENV["PAYANGEL_SECRET_KEY"]
+      @env        = (env || ENV["PAYANGEL_ENV"] || "production").to_s
+      @timeout    = (timeout || 30).to_i
+    end
+
+    def validate!
+      if @public_key.nil? || @public_key.to_s.strip.empty?
+        raise AuthenticationError.new(
+          "Missing public key. Pass public_key: to the client or set PAYANGEL_PUBLIC_KEY.",
+          http_status: 0
+        )
+      end
+
+      if @secret_key.nil? || @secret_key.to_s.strip.empty?
+        raise AuthenticationError.new(
+          "Missing secret key. Pass secret_key: to the client or set PAYANGEL_SECRET_KEY.",
+          http_status: 0
+        )
+      end
+
+      unless ENVIRONMENTS.key?(@env)
+        raise ArgumentError, "env must be 'sandbox' or 'production', got '#{@env}'"
+      end
+
+      self
+    end
+
+    def base_url
+      ENVIRONMENTS.fetch(@env)
+    end
+  end
+end