paystack_sdk 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d2f7a168f41486d2df726ca96f7f6ff1864e4f66b46a019a3894385c5a74a16
-  data.tar.gz: d2f63d9282c6fd568c8e9c16d7b91bbb65fe874fea489420af92f0336f9431e2
+  metadata.gz: 02712537eff419059ff52364f7f6077b8b40fd171a2f29326d74e2475aa28482
+  data.tar.gz: cf8537555639790e816ade12badb9e0ba177c5c76f9bb2142d70d81c3dfb8540
 SHA512:
-  metadata.gz: 9470f85d1e68ec70caa4b50e02c3ab001eef9490d2f562294c1067316ca12b43c6f6f74e876750b1ef8da6d2f88c88b56f0d2eeb234e95d92162fd4e09afd6ec
-  data.tar.gz: 92d8ddbc6768188517ad0dc39b36b64adb0faac6c13fa4a3c1b8bd29f6c8977f028b18c3ef892bd7e483c801eed68783a4e35607acf2cbd51fb3ac349cb1a70f
+  metadata.gz: 7d833404efed23211c319b6b629c3158e6b1013538fb32648d76fe1fef445c79291b8c01c4291054b98e39cc71c0364060b2a0fcbd10b2673cc58b22a7bc5fd0
+  data.tar.gz: fc869da180ae8333a892b46e72768de8f85daa3b9b53bef1ad9a2893dc2d8fe453ffe227a4acb8e14afcda6ba750a59d24049cef99bb9630b1199d8933f8e916

data/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-10
+
+### Upgrading from 0.4
+
+Two behaviours changed in small ways. Check them if you use these calls:
+
+- `transactions.initiate` sends `metadata` stringified, as Paystack documents it, so numbers in it keep their type when you read them back (`{count: 42}` stays `42`; it used to come back as `"42"`).
+- Filters that take a numeric ID (`customer_id:`, `plan_id:`, `transaction_id:` and `authorization_id:`) raise `InvalidValueError` for anything but a numeric ID. Paystack used to answer a code such as `CUS_abc123` there with an empty list and no error, so if you passed one you were silently getting nothing.
+
+If you are on 0.4.0, take 0.4.1 first if you only need the security fix.
+
+### Added
+
+- `Response#dig(*keys)` reads a nested value and returns `nil` as soon as a key is missing, for fields Paystack only sometimes sends (`response.dig(:authorization, :authorization_code)`). Dot access still raises `NoMethodError` for a key that is not there, which catches typos.
+- The `paystack-sdk-overview` skill now has a "Topic skills" table that routes an agent to the right skill for the task, and the skills link to each other with `[[name]]`. A spec fails if a shipped skill is not reachable from the overview.
+- `client.webhook_events` (Paystack's Webhook Events API: `list`, `lookup`, `fetch`, `resend`, `resend_matching`), the log of the webhooks Paystack sent you with their delivery status, the payload and what your endpoint answered. It is documented by Paystack but not in its OpenAPI spec, so it is hand-written and recorded in `spec/fixtures/docs_only_operations.yml`; `bin/paystack-spec audit` and the contract checker read that file. `list`, `lookup` and `fetch` were checked against the test API; `resend` and `resend_matching` were not (they deliver webhooks to your endpoint), and `resend_matching` requires `preview:`.
+- `Webhook::EVENTS` also lists `refund.needs-attention` (named in Paystack's Refunds guide) and `paymentrequest.draft`, `product.create`, `product.update` and `product.delete`, which Paystack was seen sending but its Webhooks page does not list.
+- Skills `paystack-sdk-charge-statuses` (what each charge `status` means, what to show the payer, which `charges.*` call comes next, and why `success?` is not "the charge worked"; the flows were reproduced on the test API with Paystack's test cards) and `paystack-sdk-mobile-money` (Ghana providers and codes, the phone number form, the 180-second approval window, how the result arrives, and what test mode does not prove). Specs run what they say.
+- Skill `paystack-sdk-webhooks`: receiving Paystack webhooks in Rails or Rack with `PaystackSdk::Webhook` (signature over the raw body, `verify!` vs `valid_signature?` vs `construct_event` and their errors, CSRF, the optional IP allow-list, answering 200 fast, the documented retry policy, duplicate and out-of-order deliveries, verifying by reference before granting value, the documented events, and testing with a signed request). Its Ruby is run by `spec/skills_webhooks_spec.rb`; payload fields beyond Paystack's one documented sample are marked unverified.
+- Skill `paystack-sdk-refunds`: full and partial refunds, the pending-until-processed lifecycle, what to record, refund webhooks, and what to do after a timeout. Includes what the test API showed (a GHS 1.00 minimum per refund, an omitted `amount` asks for the whole original amount and fails after a partial refund, a refunded transaction verifies as `reversal-pending`) and marks the rest unverified.
+- Skill `paystack-sdk-money-safety`: the checklist for any code that moves or records money (integer minor-unit amounts, verifying by reference with `paid?(amount:, currency:)` and the customer email before granting value, never resending a write after a timeout, reference discipline, storing only the encrypted authorization code, keeping keys out of logs, `sandbox_only` limits, webhook and reconciliation rules) with a pre-merge table. Its claims are run by `spec/skills_money_safety_spec.rb` or were observed on the Paystack test API.
+- Skill `paystack-sdk-testing`: keys for test, staging and CI (`sandbox_only`, `live?` and what they do not check), a copyable WebMock helper with success, 400, 401, 429, 500 and timeout stubs (each run through the SDK in the gem's specs), an opt-in test-API suite pattern, Paystack's published test cards and the MTN test number, testing a webhook endpoint with `Webhook.sign`, and what test mode cannot prove.
+- Skill `paystack-sdk-saved-card-renewals`: charging a returning customer's saved card on your own schedule with `transactions.charge_authorization`. Covers saving only `reusable` authorizations keyed to their email, the responses observed on the Paystack test API (invalid, inactive, other-email and mobile money codes, duplicate references), lookup-first renewal references and the never-retry-after-timeout rule, partial debit (refused for GHS on the test API), the reported confirmation race, mobile money having no reusable token, and dunning advice. Its helper code is run by `spec/skills_saved_card_renewals_spec.rb`.
+- Skill `paystack-sdk-payments`: the hosted checkout flow with `client.transactions` (`initiate` keywords, redirecting to `authorization_url`, why the callback proves nothing, `verify` and `paid?`, what each verify status means, idempotent confirmation from the callback and the webhook as labelled design advice, which fields to store, `fetch` and `list`). Its claims are run by `spec/skills_payments_spec.rb` or were observed on Paystack's test API; the checkout page itself could not be driven and is marked unverified.
+- AI skills for Claude Code, shipped in the gem and installed with `paystack_sdk skills install` (any Ruby project) or `rails generate paystack_sdk:skills` (Rails) into `.claude/skills/`. The first skill is `paystack-sdk-overview`. Installing is idempotent, writes only `paystack-sdk-<topic>` folders marked with `.paystack_sdk.json`, never overwrites a folder it did not install (`--force` to replace), removes only its own stale folders, stamps each `SKILL.md` with the gem version, and supports `--dir`, `--global` and `--dry-run`. Also `skills list`, `skills path` and `skills uninstall`.
+- The `paystack_sdk` executable (`exe/paystack_sdk`); it handles the skills and `version` and does not load Faraday.
+
+### Fixed
+
+- `transactions.initiate` now sends `metadata` stringified, as `charge_authorization` already did and as Paystack documents it. Paystack accepts an object too, but stores it differently: a nested number comes back as a string (`{count: 42}` as `{"count" => "42"}`), whereas a stringified object keeps it (`42`). Checked against the test API. If you read numbers back out of `metadata`, they are now numbers.
+- Filters that take a numeric ID (`customer_id:` on `transactions.list`, `transactions.export`, `subscriptions.list` and `payment_requests.list`, `plan_id:` on `subscriptions.list`, `transaction_id:` on `refunds.list`, `authorization_id:` on `customers.direct_debit_activation_charge`) now refuse anything but a numeric ID (an Integer, or a string of digits) with `InvalidValueError`. Paystack answers a code such as `CUS_abc123` there with an empty list and no error, which looks like "no results". If you passed a code to one of these, you were silently getting nothing.
+- Passing a String date or date-time to a `from:` or `to:` filter (`transactions.list(from: "2026-10-01")`, and every other date filter) raised `NoMethodError: undefined method 'iso8601' for class Time` in a plain Ruby process, because the gem never loaded Ruby's `time` library. It only worked where something else had loaded it, such as Rails or RSpec. The gem now requires it. A Date or Time object was never affected.
+
 ## [0.4.1] - 2026-10-10
 
 ### Security

data/README.md

@@ -4,6 +4,7 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
 
 ## Table of Contents
 
+- [AI Skills](#ai-skills)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
@@ -100,8 +101,10 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
     - [List and Fetch Terminals](#list-and-fetch-terminals)
     - [Send an Event and Check It](#send-an-event-and-check-it)
     - [Update, Commission and Decommission](#update-commission-and-decommission)
+  - [Webhook Events](#webhook-events)
   - [Response Handling](#response-handling)
     - [Working with Response Objects](#working-with-response-objects)
+    - [Optional Fields: `dig`](#optional-fields-dig)
     - [Accessing the Original Response](#accessing-the-original-response)
     - [Error Handling](#error-handling)
 - [Advanced Usage](#advanced-usage)
@@ -115,6 +118,25 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
 
+## AI Skills
+
+The gem ships skills for AI coding agents (Claude Code `SKILL.md` folders) that teach an agent how to use `paystack_sdk` correctly: the conventions, what raises and what returns, and the checks that keep money safe. They are installed from the gem you have, so they match its version.
+
+```sh
+# Any Ruby project: installs into ./.claude/skills
+bundle exec paystack_sdk skills install
+
+# A Rails app
+bin/rails generate paystack_sdk:skills
+```
+
+- **Safe to repeat.** A second run reports `identical`. After a gem upgrade, run it again: it updates only the folders it installed.
+- **Never overwrites your skills.** Every folder it writes is named `paystack-sdk-<topic>` and carries a `.paystack_sdk.json` marker. A folder with the same name that it did not install is left alone and reported as a `conflict` (`--force` replaces it). It removes only its own folders that a newer gem no longer ships.
+- **Version-stamped.** Each installed `SKILL.md` records the gem version in its frontmatter (`metadata.gem_version`).
+- Options: `--dir DIR` (another directory), `--global` (`~/.claude/skills`), `--dry-run` (change nothing; `rails generate ... --pretend` in Rails). Other commands: `paystack_sdk skills list`, `skills path` (where the skills live inside the gem, for agents that read files directly), `skills uninstall`, `paystack_sdk version`.
+
+Run `paystack_sdk skills list` for the skills in your installed version and when each one applies. Each is a `paystack-sdk-<topic>` folder; an agent picks them from their descriptions.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -1763,6 +1785,37 @@ paystack.terminals.commission(serial_number: "1111150412230003899")
 paystack.terminals.decommission(serial_number: "1111150412230003899")
 ```
 
+### Webhook Events
+
+The Webhook Events API is the log of every webhook Paystack tried to send to your integration's webhook URL: whether it was delivered, what Paystack sent, and what your endpoint answered. It is documented by Paystack but is not in its OpenAPI spec, so `client.webhook_events` is written from the docs (the entry in `spec/fixtures/docs_only_operations.yml` records what was checked). Use it to find out why a webhook never arrived, to see the exact payload, and to replay events your endpoint missed.
+
+```ruby
+# Events Paystack could not deliver (status is Delivered, Pending or Failed)
+response = paystack.webhook_events.list(status: "Failed", limit: 20)
+
+response.each do |event|
+  puts "#{event.event_name} #{event.status} (#{event.status_detail}) answered #{event.response_code}"
+end
+
+# The next page: pass meta.next back as next_cursor (not together with previous)
+paystack.webhook_events.list(next_cursor: response.original_response.dig("meta", "next"))
+
+# Filters: category, event_type, status, category_row_id, from, to
+paystack.webhook_events.list(event_type: "charge.success", from: Date.new(2025, 6, 1))
+
+# One event in full: the payload Paystack sent, and your endpoint's answer
+event = paystack.webhook_events.fetch(id: "6ac94b47fdad55440ef2066a")
+event.event_payload[:data] # brackets: a key named data is not reachable with dot access
+event.merchant_response_body
+
+# Find an event by its own id, or by the id of the resource it is about (a transaction id)
+paystack.webhook_events.lookup(id: 6_641_907_106)
+```
+
+Checked against Paystack's test API: `list`, `lookup` and `fetch` (read-only). A page holds 50 events by default (the docs say 20) and `limit` is capped at 50. Every event has a `_id`; the payloads Paystack records are `{"event": ..., "data": {...}}` with no event id inside, and `data.id` was present in every payload seen.
+
+**Resending is unverified and makes Paystack deliver webhooks to your endpoint.** `resend(ids:)` and `resend_matching(preview:, filters:)` were never called: the docs say resending is not idempotent, so your endpoint must dedupe. `resend_matching` makes you choose `preview:` (the docs make it optional) because with no filters it resends everything. Call it with `preview: true` first.
+
 ### Response Handling
 
 #### Working with Response Objects
@@ -1820,6 +1873,21 @@ response.meta.perPage    # => 20
 
 `response.meta` is `nil` when the response has no `meta`.
 
+#### Optional Fields: `dig`
+
+Dot access raises `NoMethodError` for a key that is not in the response. That is what you want for a typo, but not for a field Paystack only sometimes sends (`paid_at` on an unpaid transaction, `authorization` details on a payment without a card). Read those with `dig`: it returns `nil` as soon as a key along the path is missing, accepts strings or symbols (and an Integer to index an Array), and returns the value as it is, like `Hash#dig`.
+
+```ruby
+response = paystack.transactions.verify(reference: "order-1042")
+
+response.dig(:paid_at)                              # => "2025-06-01T10:00:00.000Z" or nil
+response.dig(:authorization, :authorization_code)   # => "AUTH_xxxx" or nil
+response.dig(:customer, :email)                     # => "ama@example.com"
+response.dig(:log, :history, 0, :message)           # an Integer indexes an Array
+```
+
+`response[:key]` also gives `nil` for a missing key, but wraps what it finds in a `Response`; `dig` gives you the plain value.
+
 #### Accessing the Original Response
 
 Sometimes you may need access to the original API response:

data/exe/paystack_sdk

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/paystack_sdk/cli"
+
+exit PaystackSdk::CLI.run(ARGV)

data/lib/generators/paystack_sdk/skills_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "paystack_sdk/skills"
+
+module PaystackSdk
+  module Generators
+    # `rails generate paystack_sdk:skills`: installs the gem's AI skills into the app's `.claude/skills/`.
+    # It never overwrites a skill folder it did not install, and after a gem upgrade it updates only its
+    # own folders. `--pretend` shows what would happen.
+    class SkillsGenerator < Rails::Generators::Base
+      desc "Install the paystack_sdk AI skills into .claude/skills/ (Claude Code)"
+
+      class_option :force, type: :boolean, default: false, desc: "Replace a same-named folder paystack_sdk did not install"
+
+      COLORS = {"create" => :green, "update" => :yellow, "force" => :yellow, "remove" => :red, "conflict" => :red}.freeze
+
+      def install_skills
+        dir = File.join(destination_root, ".claude", "skills")
+        results = PaystackSdk::Skills.install(dir, dry_run: options[:pretend], force: options[:force])
+
+        results.each { |r| say_status(r.status, [r.name, r.note].compact.join(": "), COLORS.fetch(r.status, :blue)) }
+        say_status("note", "Some skill folders were left alone; run with --force to replace them.", :red) if results.any? { |r| r.status == "conflict" }
+      end
+    end
+  end
+end

data/lib/paystack_sdk/cli.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "skills"
+require_relative "version"
+
+module PaystackSdk
+  # The `paystack_sdk` command. It only handles the AI skills; it does not load Faraday or call Paystack.
+  #
+  #   paystack_sdk skills install [--dir DIR | --global] [--dry-run] [--force]
+  #   paystack_sdk skills list
+  #   paystack_sdk skills path
+  #   paystack_sdk skills uninstall [--dir DIR | --global] [--dry-run]
+  #   paystack_sdk version
+  class CLI
+    USAGE = <<~TEXT
+      Usage:
+        paystack_sdk skills install [--dir DIR | --global] [--dry-run] [--force]
+        paystack_sdk skills uninstall [--dir DIR | --global] [--dry-run]
+        paystack_sdk skills list
+        paystack_sdk skills path
+        paystack_sdk version
+
+      `skills install` copies the AI skills that ship with this gem into .claude/skills/ (Claude Code),
+      ready for an agent to load. It is safe to repeat, never overwrites a skill folder it did not
+      install, and after a gem upgrade updates only its own folders.
+
+      Options:
+        --dir DIR    install into DIR instead of ./.claude/skills
+        --global     install into ~/.claude/skills
+        --dry-run    say what would happen and change nothing
+        --force      replace a same-named folder that paystack_sdk did not install
+    TEXT
+
+    # Runs the command.
+    #
+    # @param argv [Array<String>]
+    # @param out [IO]
+    # @param err [IO]
+    # @return [Integer] the exit status
+    def self.run(argv, out: $stdout, err: $stderr)
+      new(out: out, err: err).run(argv.dup)
+    end
+
+    def initialize(out:, err:)
+      @out = out
+      @err = err
+    end
+
+    def run(argv)
+      command = argv.shift
+      case command
+      when "skills" then skills(argv)
+      when "version", "--version", "-v" then @out.puts("paystack_sdk #{VERSION}").then { 0 }
+      when nil, "help", "--help", "-h" then @out.puts(USAGE).then { 0 }
+      else fail_with("unknown command #{command.inspect}")
+      end
+    rescue OptionParser::ParseError => e
+      fail_with(e.message)
+    end
+
+    private
+
+    def skills(argv)
+      sub = argv.shift
+      case sub
+      when "install" then install(argv)
+      when "uninstall" then uninstall(argv)
+      when "list" then list
+      when "path" then @out.puts(Skills::SOURCE_DIR).then { 0 }
+      else fail_with("unknown skills command #{sub.inspect}")
+      end
+    end
+
+    def install(argv)
+      options = parse(argv, force: true)
+      dir = target(options)
+      results = Skills.install(dir, dry_run: options[:dry_run], force: options[:force])
+      report(results, dir, options)
+      (results.any? { |r| r.status == "conflict" }) ? 1 : 0
+    end
+
+    def uninstall(argv)
+      options = parse(argv, force: false)
+      dir = target(options)
+      results = Skills.uninstall(dir, dry_run: options[:dry_run])
+      report(results, dir, options)
+      0
+    end
+
+    def list
+      Skills.all.each { |skill| @out.puts("#{skill.name}\n    #{skill.description}") }
+      0
+    end
+
+    def parse(argv, force:)
+      options = {}
+      OptionParser.new do |o|
+        o.on("--dir DIR") { |v| options[:dir] = v }
+        o.on("--global") { options[:global] = true }
+        o.on("--dry-run") { options[:dry_run] = true }
+        o.on("--force") { options[:force] = true } if force
+      end.parse!(argv)
+      raise OptionParser::InvalidOption, argv.first unless argv.empty?
+      raise OptionParser::InvalidOption, "--dir and --global together" if options[:dir] && options[:global]
+
+      options
+    end
+
+    def target(options)
+      return File.expand_path(options[:dir]) if options[:dir]
+      return File.join(Dir.home, ".claude", "skills") if options[:global]
+
+      File.join(Dir.pwd, ".claude", "skills")
+    end
+
+    def report(results, dir, options)
+      @out.puts("#{"Dry run: " if options[:dry_run]}#{dir}")
+      results.each do |r|
+        @out.puts("#{r.status.rjust(12)}  #{r.name}#{"  (#{r.note})" if r.note}")
+      end
+      @out.puts("\nDry run: nothing was written.") if options[:dry_run]
+      @out.puts("\nSome folders were left alone. Re-run with --force to replace them.") if results.any? { |r| r.status == "conflict" }
+    end
+
+    def fail_with(message)
+      @err.puts("paystack_sdk: #{message}\n\n#{USAGE}")
+      1
+    end
+  end
+end

data/lib/paystack_sdk/client.rb

@@ -27,6 +27,7 @@ require_relative "resources/integrations"
 require_relative "resources/virtual_terminals"
 require_relative "resources/direct_debits"
 require_relative "resources/terminals"
+require_relative "resources/webhook_events"
 require_relative "utils/connection_utils"
 
 module PaystackSdk
@@ -344,6 +345,18 @@ module PaystackSdk
       @terminals ||= Resources::Terminals.new(@connection)
     end
 
+    # Provides access to the `WebhookEvents` resource: the log of webhooks Paystack sent you, with their
+    # delivery status, and a way to send them again. (Not in Paystack's OpenAPI spec; from its docs.)
+    #
+    # @return [PaystackSdk::Resources::WebhookEvents] An instance of the
+    #  `WebhookEvents` resource.
+    #
+    # @example
+    #   client.webhook_events.list(status: "Failed")
+    def webhook_events
+      @webhook_events ||= Resources::WebhookEvents.new(@connection)
+    end
+
     # A short description that never includes the secret key. Ruby's default `inspect` prints every
     # instance variable, and the connection holds the key in its `Authorization` header, so logging,
     # `pp`, an error page or an error tracker would otherwise write the key out.

data/lib/paystack_sdk/request_helpers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "date"
+require "time"
 require "erb"
 require "json"
 

data/lib/paystack_sdk/resources/customers.rb

@@ -2,7 +2,7 @@
 
 # Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
 # Do not edit by hand: regenerate it with `bin/paystack-scaffold Customer`. Hand-written extras go in lib/paystack_sdk/resources/extensions/customers.rb.
-# scaffold-digest: 24269cd1f96877a533fed260bdce25e0dc552ebe7ca1c5636362779e27358054
+# scaffold-digest: f23af37740665b121f36ec65dd45f1275b9b4358e704cf85b43f6cdd3218adae
 
 require_relative "base"
 
@@ -281,6 +281,7 @@ module PaystackSdk
       def direct_debit_activation_charge(id:, authorization_id:)
         validate_presence!(value: id, name: "id")
         validate_presence!(value: authorization_id, name: "authorization_id")
+        validate_numeric_id!(value: authorization_id, name: "authorization_id", allow_nil: false)
 
         wire_body = to_wire({authorization_id:}, WIRE_NAMES)
 

data/lib/paystack_sdk/resources/payment_requests.rb

@@ -2,7 +2,7 @@
 
 # Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
 # Do not edit by hand: regenerate it with `bin/paystack-scaffold Payment Request`. Hand-written extras go in lib/paystack_sdk/resources/extensions/payment_requests.rb.
-# scaffold-digest: 884176d0fce2f23befd4655d04efd15b5dccf6808f496f41b09e0afcd43c1e73
+# scaffold-digest: cfe9d7cb1a4ff04446434e6a6d3b3ca134e3b04e3b2a223d3f50e546ef6e9c3e
 
 require_relative "base"
 
@@ -40,6 +40,7 @@ module PaystackSdk
       )
         validate_positive_integer!(value: per_page, name: "perPage")
         validate_positive_integer!(value: page, name: "page")
+        validate_numeric_id!(value: customer_id, name: "customer")
         validate_allowed_values!(
           value: status,
           allowed_values: %w[draft pending success failed],

data/lib/paystack_sdk/resources/refunds.rb

@@ -2,7 +2,7 @@
 
 # Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
 # Do not edit by hand: regenerate it with `bin/paystack-scaffold Refund`. Hand-written extras go in lib/paystack_sdk/resources/extensions/refunds.rb.
-# scaffold-digest: c3b04aa2ea57cc443996cfdf4b3432aa4839b01df431c881aa247d2c97514a1b
+# scaffold-digest: a937a81e9f6e991fee25d3817854912d092e7ebc140f6deffc87a3bef23bd5ba
 
 require_relative "base"
 
@@ -28,6 +28,7 @@ module PaystackSdk
       def list(per_page: nil, page: nil, from: nil, to: nil, transaction_id: nil)
         validate_positive_integer!(value: per_page, name: "perPage")
         validate_positive_integer!(value: page, name: "page")
+        validate_numeric_id!(value: transaction_id, name: "transaction")
 
         wire_query = to_wire(
           {

data/lib/paystack_sdk/resources/subscriptions.rb

@@ -2,7 +2,7 @@
 
 # Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
 # Do not edit by hand: regenerate it with `bin/paystack-scaffold Subscription`. Hand-written extras go in lib/paystack_sdk/resources/extensions/subscriptions.rb.
-# scaffold-digest: bf9e49fa6de4d23b295572c9c4fc3aa74477986410dd3f858145f2e4239d0444
+# scaffold-digest: afa2b5d66179938b017341e73f1617480718a7b043c2b051c437fad1b209f893
 
 require_relative "base"
 
@@ -29,6 +29,8 @@ module PaystackSdk
       def list(per_page: nil, page: nil, plan_id: nil, customer_id: nil, from: nil, to: nil)
         validate_positive_integer!(value: per_page, name: "perPage")
         validate_positive_integer!(value: page, name: "page")
+        validate_numeric_id!(value: plan_id, name: "plan")
+        validate_numeric_id!(value: customer_id, name: "customer")
 
         wire_query = to_wire(
           {

data/lib/paystack_sdk/resources/transactions.rb

@@ -2,7 +2,7 @@
 
 # Generated by bin/paystack-scaffold from Paystack's OpenAPI spec (PaystackOSS/openapi@d9d444d).
 # Do not edit by hand: regenerate it with `bin/paystack-scaffold Transaction`. Hand-written extras go in lib/paystack_sdk/resources/extensions/transactions.rb.
-# scaffold-digest: c0b49a40a718c09c83eb9a496eb40d1f7cd4c1387b54efa3cfe360906be89f0e
+# scaffold-digest: e2ec619d787ab4bb8a5c5c09e4c0df028f645a578b41df012aad09174ce3eca2
 
 require_relative "base"
 
@@ -31,7 +31,7 @@ module PaystackSdk
       # @param transaction_charge [String] A flat fee to charge the subaccount for a transaction.
       # @param bearer [String] The bearer of the transaction charge One of: account, subaccount.
       # @param label [String] Used to replace the email address shown on the Checkout
-      # @param metadata [Hash] JSON object of custom data
+      # @param metadata [String] Custom data as a JSON object (a Hash, or a JSON string).
       # @return [PaystackSdk::Response] The response from the Paystack API.
       # @raise [PaystackSdk::Error] If a parameter is invalid or the API request fails.
       # @see https://paystack.com/docs/api/transaction/#initialize
@@ -84,7 +84,7 @@ module PaystackSdk
             transaction_charge:,
             bearer:,
             label:,
-            metadata:
+            metadata: stringify_json(metadata)
           },
           WIRE_NAMES
         )
@@ -283,6 +283,7 @@ module PaystackSdk
           allowed_values: %w[merchantApi checkout pos virtualTerminal],
           name: "source"
         )
+        validate_numeric_id!(value: customer_id, name: "customer")
         validate_positive_integer!(value: amount, name: "amount")
         validate_allowed_values!(
           value: channel,
@@ -372,7 +373,7 @@ module PaystackSdk
       # @param from [String] The start date
       # @param to [String] The end date
       # @param status [String] Filter by the status of the transaction One of: success, failed, abandoned, reversed, all.
-      # @param customer_id [Numeric] Filter by customer ID
+      # @param customer_id [Integer] Filter by customer ID
       # @param subaccount_code [String] Filter by subaccount code
       # @param settlement [Integer] Filter by the settlement ID
       # @param currency [String] Specify the transaction currency to export.
@@ -399,6 +400,7 @@ module PaystackSdk
           allowed_values: %w[success failed abandoned reversed all],
           name: "status"
         )
+        validate_numeric_id!(value: customer_id, name: "customer")
         validate_positive_integer!(value: amount, name: "amount")
 
         wire_query = to_wire(