paystack_sdk 0.4.1 → 0.5.0

data/lib/paystack_sdk/resources/webhook_events.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# Hand-written from Paystack's docs (https://paystack.com/docs/api/webhook-events/). These operations are not in
+# Paystack's OpenAPI spec, so the scaffold cannot generate them; they are recorded, with what was and was not
+# observed, in spec/fixtures/docs_only_operations.yml.
+
+require_relative "base"
+
+module PaystackSdk
+  module Resources
+    # Webhook Events API: the log of webhooks Paystack has sent to your integration's webhook URL, with their
+    # delivery status, the payload that was sent and what your endpoint answered, and a way to send them
+    # again. Use it to find out whether a webhook was delivered, to see exactly what Paystack sent, and to
+    # recover events your endpoint missed.
+    #
+    # `list`, `lookup` and `fetch` only read. `resend` and `resend_matching` make Paystack deliver webhooks
+    # to your endpoint again, and have **not** been called against the Paystack test API.
+    class WebhookEvents < PaystackSdk::Resources::Base
+      # Delivery statuses the API accepts for the `status` filter (anything else is a 400).
+      STATUSES = %w[Delivered Pending Failed].freeze
+
+      # The filters List Events takes, which Resend Matching Events accepts too.
+      FILTERS = %w[category event_type status category_row_id from to].freeze
+
+      # The most event ids Paystack accepts in one resend.
+      MAX_RESEND_IDS = 100
+
+      # Ruby keyword => the parameter name Paystack documents.
+      WIRE_NAMES = {next_cursor: "next", id: "reference"}.freeze
+
+      # List Events.
+      #
+      # Fetches a page of the webhook events sent to your integration, newest first. The response `meta` holds
+      # `next` and `previous` cursors: pass `meta.next` back as `next_cursor:` for the next page.
+      #
+      # Observed on the Paystack test API (2026-10-09), where the docs differ: a page holds 50 events by
+      # default (the docs say 20), `limit` is capped at 50, and a `limit` that is not a number is ignored.
+      #
+      # @param category [String] Filter by category, for example "transactions" or "refund".
+      # @param event_type [String] Filter by event name, for example "charge.success".
+      # @param status [String] Filter by delivery status: Delivered, Pending or Failed.
+      # @param category_row_id [String, Integer] Filter by the ID of the resource the event is about, such as a
+      #   transaction ID.
+      # @param from [String, Time, Date] Only events from this time on, for example 2016-09-24T00:00:05.000Z or 2016-09-21.
+      # @param to [String, Time, Date] Only events up to this time.
+      # @param limit [Integer] How many events to return per page.
+      # @param next_cursor [String] The `meta.next` cursor of a previous response (sent as `next`). Not together with `previous`.
+      # @param previous [String] The `meta.previous` cursor of a previous response. Not together with `next_cursor`.
+      # @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/webhook-events/#list
+      def list(category: nil, event_type: nil, status: nil, category_row_id: nil, from: nil, to: nil, limit: nil,
+        next_cursor: nil, previous: nil)
+        validate_allowed_values!(value: status, allowed_values: STATUSES, name: "status")
+        validate_positive_integer!(value: limit, name: "limit")
+        reject_both_cursors!(next_cursor, previous)
+
+        wire_query = to_wire(
+          {
+            category:, event_type:, status:, category_row_id:,
+            from: format_datetime(from, name: "from"),
+            to: format_datetime(to, name: "to"),
+            limit:, next_cursor:, previous:
+          },
+          WIRE_NAMES
+        )
+
+        handle_response(@connection.get("/integration/webhooks/events", wire_query))
+      end
+
+      # Look Up an Event.
+      #
+      # Finds a webhook event by its own ID, or by the ID of the resource it is about (a transaction ID, not
+      # the transaction's reference). Observed on the test API: an event's `_id` and a `category_row_id`
+      # both match; a value that matches nothing is a 404 "Webhook not found" (an unsuccessful Response).
+      #
+      # @param id [String, Integer] An event `_id`, or the ID of the resource it is about. Sent as `reference`, the name
+      #   Paystack's docs give it, although it is not a reference.
+      # @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/webhook-events/#lookup
+      def lookup(id:)
+        validate_presence!(value: id, name: "id")
+
+        handle_response(@connection.get("/integration/webhooks/events/lookup", to_wire({id:}, WIRE_NAMES)))
+      end
+
+      # Fetch Event.
+      #
+      # Gets one event in full: `event_payload` (the body Paystack sent), `webhook_url`, `status`,
+      # `status_detail`, `response_code`, `merchant_response_body` (what your endpoint answered), `trial_count`
+      # and `trials`. Observed on the test API, where `event_payload` is a Hash with the keys `event` and
+      # `data`. Read the payload's own `data` with brackets, `response.event_payload[:data]`: dot access
+      # `event_payload.data` returns the Response itself, because `Response#data` is a method.
+      #
+      # @param id [String] The event's `_id`, from an item of {#list}.
+      # @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/webhook-events/#fetch
+      def fetch(id:)
+        validate_presence!(value: id, name: "id")
+
+        handle_response(@connection.get("/integration/webhooks/events/#{escape_path(id, name: "id")}"))
+      end
+
+      # Resend Events.
+      #
+      # Asks Paystack to deliver a specific set of events to your current webhook URL again.
+      #
+      # @note This makes Paystack send webhooks to your endpoint. The docs say resending is not idempotent:
+      #   sending the same event ID twice delivers it twice, so your endpoint must dedupe. It has not been
+      #   called against the Paystack test API; the method follows the docs.
+      #
+      # @param ids [Array<String>] The `_id`s of the events to resend: not empty, at most 100.
+      # @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/webhook-events/#resend
+      def resend(ids:)
+        unless ids.is_a?(Array) && !ids.empty? && ids.size <= MAX_RESEND_IDS && ids.all? { |id| id.is_a?(String) && !id.strip.empty? }
+          raise PaystackSdk::InvalidValueError.new("ids", "must be a non-empty Array of event _id strings, at most #{MAX_RESEND_IDS}")
+        end
+
+        handle_response(@connection.post("/integration/webhooks/events/resend", {ids: ids}))
+      end
+
+      # Resend Matching Events.
+      #
+      # Asks Paystack to deliver every event that matches the filters to your current webhook URL again.
+      # With `preview: true` it only counts the matching events.
+      #
+      # `preview:` has no default here, although the docs make it optional: with no filters this resends
+      # every event, so you have to say which you mean. Call it with `preview: true` first.
+      #
+      # @note This can make Paystack send a lot of webhooks to your endpoint, which must dedupe. It has not
+      #   been called against the Paystack test API, including with `preview: true`; the method follows
+      #   the docs.
+      #
+      # @param preview [Boolean] true to return the matching count without resending anything; false to resend.
+      # @param filters [Hash, nil] Any of the {#list} filters: category, event_type, status, category_row_id, from, to.
+      # @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/webhook-events/#resend-matching
+      def resend_matching(preview:, filters: nil)
+        unless [true, false].include?(preview)
+          raise PaystackSdk::InvalidValueError.new("preview", "must be true (count only) or false (resend)")
+        end
+
+        body = filters.nil? ? {} : {filters: checked_filters(filters)}
+        handle_response(@connection.post("/integration/webhooks/events/resend-matching?preview=#{preview}", body))
+      end
+
+      private
+
+      # `next` and `previous` together are a 400 from the API ("must be one of next or previous").
+      def reject_both_cursors!(next_cursor, previous)
+        return unless next_cursor && previous
+
+        raise PaystackSdk::InvalidValueError.new("next_cursor", "cannot be used together with previous")
+      end
+
+      def checked_filters(filters)
+        validate_hash!(input: filters, name: "filters")
+        stringified = filters.transform_keys(&:to_s)
+        unknown = stringified.keys - FILTERS
+        raise PaystackSdk::InvalidValueError.new("filters", "unknown filter(s) #{unknown.join(", ")}; allowed: #{FILTERS.join(", ")}") unless unknown.empty?
+
+        validate_allowed_values!(value: stringified["status"], allowed_values: STATUSES, name: "filters status")
+        stringified["from"] = format_datetime(stringified["from"], name: "filters from") if stringified.key?("from")
+        stringified["to"] = format_datetime(stringified["to"], name: "filters to") if stringified.key?("to")
+        compact_params(stringified)
+      end
+    end
+  end
+end

data/lib/paystack_sdk/response.rb

@@ -248,6 +248,31 @@ module PaystackSdk
       end
     end
 
+    # Reads a nested value from the data, or nil as soon as a key is missing. Use it for fields Paystack
+    # only sometimes sends (`paid_at`, `authorization.exp_month`...): dot access raises `NoMethodError`
+    # for a key that is not there, which is what you want for a typo and not for an optional field.
+    # Keys can be strings or symbols; an Integer indexes an Array. The value is returned as it is (a
+    # plain Hash, Array or scalar), like `Hash#dig`.
+    #
+    # @param keys [Array<String, Symbol, Integer>] The path to the value
+    # @return [Object, nil] The value, or nil if any key along the path is missing
+    #
+    # @example
+    #   response.dig(:authorization, :authorization_code) # => "AUTH_..." or nil
+    def dig(*keys)
+      raise ArgumentError, "dig needs at least one key" if keys.empty?
+
+      keys.reduce(@raw_data) do |node, key|
+        value = case node
+        when Hash then [key, key.to_s, key.to_s.to_sym].find { |candidate| node.key?(candidate) }&.then { |found| node[found] }
+        when Array then key.is_a?(Integer) ? node[key] : nil
+        end
+        return nil if value.nil?
+
+        value
+      end
+    end
+
     # Check if key exists in hash (as a string or a symbol)
     #
     # @param key [Symbol, String] The key to check

data/lib/paystack_sdk/skills/paystack-sdk-charge-statuses/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: paystack-sdk-charge-statuses
+description: 'Use when code starts a payment with the Charge API (card or mobile money) and must react to what comes back: a status such as send_pin, send_otp, send_phone, pay_offline, pending, failed or success, deciding what to show the payer, and which paystack_sdk call to make next. Also use when a charge call reports success? but the payment did not go through.'
+---
+
+# Charge statuses: what to show, what to call next
+
+The Charge API (`client.charges`) does not finish in one call when the payer must prove something. Each response carries `data.status`, and that status tells you what the payer must do and which call comes next. Read it with `response.status` or `response.status?(:send_pin)`.
+
+## The one trap: `success?` is not "the charge worked"
+
+`response.success?` means Paystack accepted the *call*. It says nothing about whether the *charge* succeeded. Always look at `data.status`:
+
+| What you did | `success?` | `data.status` |
+|---|---|---|
+| `charges.create`/`mobile_money` with a phone number that is too short | `true` (HTTP 200, message "Charge attempted") | `failed` |
+| `charges.check_pending` on a charge that failed | `true` (HTTP 200) | `failed` |
+| `charges.submit_pin` / `submit_otp` with a wrong PIN or OTP | `false` (HTTP 400) | `failed` |
+
+So decide with the status, and give value only with `transactions.verify(reference:).paid?(amount:, currency:)` (see the rules in [[paystack-sdk-overview]]).
+
+## Status table
+
+| `data.status` | Meaning | Show the payer | Next call |
+|---|---|---|---|
+| `success` | The charge went through | Confirmation | `transactions.verify(reference:)` then `paid?(amount:, currency:)` before giving value |
+| `send_pin` | The card needs its PIN | A PIN field | `charges.submit_pin(pin:, reference:)` |
+| `send_otp` | An OTP is needed | An OTP field, with `data.display_text` | `charges.submit_otp(otp:, reference:)` |
+| `send_phone` | A mobile number is needed | A phone field, with `data.display_text` | `charges.submit_phone(phone:, reference:)` |
+| `send_birthday` | A date of birth is needed (the bank flow; display text "Please enter your birthday") | A date field | `charges.submit_birthday(birthday:, reference:)` |
+| `send_address` (name not confirmed) | A billing address is needed | Address, city, state and zip code | `charges.submit_address(address:, city:, state:, zip_code:, reference:)` |
+| `pay_offline` | The payer approves on their phone or by USSD | `data.display_text` (and any USSD code in the response) | Nothing to submit. Wait for the `charge.success` webhook, then verify. If nothing arrives, poll `charges.check_pending(reference:)` or verify |
+| `pending` (name not confirmed) | Paystack is still processing | "Processing" | `charges.check_pending(reference:)` until it is not `pending`, or wait for the webhook |
+| `open_url` (EFT, South Africa) | The payer must finish on the provider's page | Redirect to `data.url` | Nothing to submit. Wait for the webhook, then verify |
+| `failed` | The charge is dead | The reason, `data.message` | Start a **new** charge with a **new** `reference` |
+
+Always pass the same `reference` you started the charge with to each follow-up call.
+
+## What was observed on Paystack's test API (2026-10-09, test cards from Paystack's test-payments page)
+
+These flows ran for real with `reference`s of our own, and each ended with `transactions.verify(...).paid?` true and a reusable authorization:
+
+- Card `4084 0840 8408 4081`, expiry `09/27`, CVV `408` (no validation): `success` at once.
+- Card `5078 5078 5078 5078 12`, CVV `081`, PIN `1111`: `send_pin` -> `submit_pin` -> `success`.
+- Card `5060 6666 6666 6666 666`, CVV `123`, PIN `1234`, OTP `123456`: `send_pin` -> `submit_pin` -> `send_otp` (display text "Please enter OTP (none will be sent to your phone)") -> `submit_otp` -> `success`.
+- Card `5078 5078 5078 5078 04`, CVV `884`, PIN `0000`, OTP `123456`: `send_pin` -> `send_phone` (display text "Kindly enter a mobile no (at least 10 digits)") -> `send_otp` -> `success`.
+- A wrong PIN or OTP returned HTTP 400, `data.status` `failed`, `data.message` "Incorrect PIN" or "Token Authorization Not Successful...". **The charge is dead after one wrong entry**: entering the correct OTP afterwards still failed. Start over with a new reference.
+- `submit_otp` with a reference Paystack does not know: HTTP 400, message "Transaction reference is invalid", no `data.status`.
+
+Not reproduced here: `send_birthday`, `pay_offline` and `open_url` appear in Paystack's payment-channels guide (the bank flow, mobile money and EFT) but a test charge never produced them (a mobile money charge answers `success` at once in test mode). `send_address` and `pending` are not named in the docs we read: the SDK has `submit_address` and `check_pending`, so the statuses are expected, but their exact names are not confirmed. Treat all of these as unverified. The SDK's `charges.create` has no `card:` keyword; card details go through Paystack's card API, which is only for PCI-compliant businesses. The test cards above are for Paystack's test mode only.
+
+## A loop that handles every status
+
+```ruby
+# `response` is the result of charges.create / charges.mobile_money, and `reference` is the one you chose.
+response = client.charges.mobile_money(email: email, amount: 5000, currency: "GHS", reference: reference,
+  mobile_money: {phone: "0551234987", provider: "mtn"})
+
+case response.status
+when "success"
+  # still verify by reference before giving value
+when "pay_offline", "pending"
+  # show response.display_text (when present) and wait for the charge.success webhook
+when "send_pin"
+  response = client.charges.submit_pin(pin: pin_from_payer, reference: reference)
+when "send_otp"
+  response = client.charges.submit_otp(otp: otp_from_payer, reference: reference)
+when "send_phone"
+  response = client.charges.submit_phone(phone: phone_from_payer, reference: reference)
+when "failed"
+  reason = response.original_response.dig("data", "message") # never retry the same reference
+else
+  raise "unhandled charge status: #{response.status.inspect}" # fail loudly, do not guess
+end
+```
+
+Collect the payer's input between steps; do not loop without them. The `else` branch matters: Paystack can return statuses this skill does not list.
+
+## Rules
+
+- **Branch on `data.status`, not on `success?`.**
+- **One reference per charge attempt.** A `failed` charge cannot be resumed; the retry is a new charge with a new reference.
+- **Never retry a charge call after a timeout** (the SDK does not either). First look it up: `client.transactions.verify(reference: reference)`.
+- **Store nothing the payer typed.** PINs and OTPs go straight to Paystack and are never logged or saved.
+- **Fail loudly on an unknown status**, and log the status and reference so it can be handled. The names `send_address` and `pending` are the likeliest to differ from the table.

data/lib/paystack_sdk/skills/paystack-sdk-mobile-money/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: paystack-sdk-mobile-money
+description: 'Use when charging a mobile money wallet in Ghana (MTN, Telecel, AT Money/AirtelTigo) with paystack_sdk, or any provider that uses charges.mobile_money: choosing the provider code and the phone number format, what the payer sees, how long the payer has, how to learn the result, and what test mode does not prove.'
+---
+
+# Mobile money charges (Ghana first)
+
+A mobile money charge is **merchant-started and payer-approved**: you ask Paystack to charge a wallet, the payer gets a prompt on their phone and approves it there, and the result arrives later. Your code must expect "not finished yet" as the normal answer. Statuses and next calls are in [[paystack-sdk-charge-statuses]]; this skill is the mobile money specifics.
+
+## Start a charge
+
+```ruby
+response = client.charges.mobile_money(
+  email: "ama@example.com",
+  amount: 5000,              # pesewas: GHS 50.00
+  currency: "GHS",
+  reference: reference,      # create and store it first
+  mobile_money: {phone: "0551234987", provider: "mtn"}
+)
+```
+
+`charges.mobile_money` checks the `mobile_money` object (a phone, or an `account` for an M-PESA Till; a known provider in any case, sent in lowercase) and then calls `charges.create`. It does not change the hash you pass in.
+
+## Provider codes
+
+| Network (Ghana) | `provider` | Code in `banks.list(country: "ghana", type: "mobile_money")` |
+|---|---|---|
+| MTN | `mtn` | `MTN` |
+| Telecel (formerly Vodafone) | `vod` | `VOD` (Paystack's list still names it "Vodafone") |
+| AT Money / Airtel Money (AirtelTigo) | `atl` | `ATL` |
+
+The charge takes the lowercase provider code; the bank list returns uppercase codes. The SDK accepts either case for `mobile_money:`. Network brand names change (Telecel Cash, AT Money); the codes above are what Paystack uses. Other providers `charges.mobile_money` accepts: `mpesa`, `mpesa_offline`, `mptill` (Kenya), `orange`, `wave` (Côte d'Ivoire).
+
+## The phone number
+
+Paystack's Ghana example uses the **local ten-digit form**, `0551234987`. If you store numbers in E.164 (`+233551234987`), convert before calling:
+
+```ruby
+def local_ghana_number(phone)
+  digits = phone.to_s.gsub(/\D/, "")                       # drop +, spaces and dashes
+  digits = digits.delete_prefix("233") if digits.size == 12  # +233 551234987 -> 551234987
+  digits = "0#{digits}" if digits.size == 9                  # 551234987 -> 0551234987
+  raise ArgumentError, "not a Ghana mobile number: #{phone.inspect}" unless digits.match?(/\A0\d{9}\z/)
+
+  digits
+end
+
+local_ghana_number("+233551234987") # => "0551234987"
+local_ghana_number("0551234987")    # => "0551234987"
+```
+
+What was checked, and what it does not prove: on Paystack's **test** API, `0551234987`, `+233551234987`, `233551234987`, `551234987` and `055 123 4987` were all accepted and all answered `success`; `0551234` (too short) answered `failed`. Test mode is lenient, so it cannot tell you which form live mode requires. The docs' example for Kenya recommends the country code (`+254...`); for Ghana the docs show only the local form. Use the local form for Ghana and confirm the first live charge.
+
+## What happens next (live mode, per Paystack's docs)
+
+1. The response has `data.status` `pay_offline` and `data.display_text`. Show the text to the payer.
+2. The payer approves on their phone. **They have 180 seconds**; after that the charge fails (a network-provider limit).
+3. Paystack sends the `charge.success` webhook when it succeeds. Verify by reference before giving value.
+4. If no webhook arrives after 180 seconds, call `transactions.verify(reference:)` (or `charges.check_pending(reference:)`). The reason a charge failed is in `data.message`.
+
+```ruby
+case response.status
+when "pay_offline", "pending"
+  # show response.display_text, then wait for the webhook (or poll check_pending)
+when "success"
+  # test mode answers like this at once; still verify
+when "failed"
+  # response.original_response.dig("data", "message") says why; start a new charge, new reference
+end
+```
+
+## What test mode does not prove
+
+On the test API a mobile money charge for each of `mtn`, `vod` and `atl`, on Paystack's test number `0551234987`, returned `success` immediately and `check_pending` agreed. That means the call shapes work. It says **nothing** about live behaviour: whether a given network accepts a merchant-started prompt for a given wallet, whether `pay_offline` and its display text look as documented, or how long approval takes. Treat live mobile money as unverified until the first real charge, and keep a fallback (such as emailing a payment link) for a network that refuses.
+
+## Rules
+
+- **Never give value on `pay_offline` or on the response alone.** Wait for the webhook and verify by reference with `paid?(amount:, currency:)`.
+- **Create the `reference` before the call and store it.** After a timeout the charge may exist: verify the reference first, and never repeat the call blindly (the SDK does not retry writes after a timeout).
+- **A new attempt is a new reference.** A `failed` charge is finished.
+- **Check `data.status`, not `success?`** (see [[paystack-sdk-charge-statuses]]).

data/lib/paystack_sdk/skills/paystack-sdk-money-safety/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: paystack-sdk-money-safety
+description: 'Use before writing, reviewing or merging any code that moves or records money with the paystack_sdk gem: starting or confirming a payment, granting value after a webhook or return URL, charging a saved card, handling a timeout on a write, storing card or authorization data, logging or reporting errors that touch a Paystack client, choosing keys per environment, or reconciling payments. A checklist of rules, each checked against the gem and the Paystack test API, ending in a pre-merge table.'
+---
+
+# Money safety checklist
+
+Apply every rule below before you write payment code, and run the table at the end before you merge it. The gem's conventions (client, `Response`, errors) are in [[paystack-sdk-overview]].
+
+## 1. Amounts are integers in the minor unit
+
+`5000` is GHS 50.00 (pesewas). Convert once, at the edge, from a decimal you trust: `(BigDecimal(price) * 100).to_i`. Never use a Float for money anywhere in your app.
+
+What happens to a bad amount on `transactions.initiate`:
+
+| Amount | The SDK | Paystack, if it got it (observed on the test API 2026-10-09) |
+|---|---|---|
+| `100.5` | raises `PaystackSdk::InvalidValueError`, nothing sent | HTTP 400 `"amount" must be an integer` |
+| `100.0` | raises `InvalidValueError` | **accepted**, stored as 100 |
+| `"100"` | raises `InvalidValueError` | **accepted**, stored as 100 |
+| `"100.50"` | raises `InvalidValueError` | HTTP 400 `"amount" must be an integer` |
+| `0` or `-100` | raises `InvalidValueError` | HTTP 400 `Invalid Amount Sent` |
+
+So do not bypass the SDK's check (for example through `client.connection.post`): Paystack itself silently accepts a whole Float or a numeric String.
+
+## 2. Never grant value from a webhook or a return URL alone
+
+A webhook, a callback or the payer landing on your return URL is a hint. Value is granted only after you verify **by your own reference** and compare with what **you** expected to charge, stored on your own record before the call. Never compare with the amount in the response, the webhook or the URL.
+
+```ruby
+# `payment` is your record: reference, amount (minor units), currency and email, saved before calling Paystack.
+def payment_outcome(client, payment)
+  response = client.transactions.verify(reference: payment.reference)
+  return :not_found unless response.success?
+  return :not_paid unless response.status?(:success)
+  return :mismatch unless response.paid?(amount: payment.amount, currency: payment.currency) &&
+    response.customer.email.to_s.casecmp?(payment.email)
+
+  :paid
+end
+```
+
+- `:paid`: grant value, once (see rule 8).
+- `:mismatch`: Paystack took a payment, but not the one you asked for (amount, currency or email differ). Do not grant; alert a person.
+- `:not_paid`: not (yet) paid. An initialized but unpaid transaction verified as `abandoned` on the test API. Check again later or wait for the webhook.
+- `:not_found`: the reference is unknown. Observed: HTTP 400, `success?` false, message "Transaction reference not found."; the SDK returns it, it does not raise.
+
+`paid?` with no arguments only checks the status: always pass `amount:` and `currency:`.
+
+## 3. Never retry a write after a timeout
+
+The SDK sends a write (POST, PUT, DELETE) once: a timeout or 5xx raises `PaystackSdk::TimeoutError` / `ConnectionError` / `ServerError` and is **not** repeated, because Paystack may have processed it. Writes are retried only on 429. Reads (GET, such as `verify`) are retried on network errors and 429/502/503/504.
+
+Do this instead: treat the outcome as unknown and verify the reference.
+
+```ruby
+def charge_saved_card(client, payment, authorization_code)
+  client.transactions.charge_authorization(email: payment.email, amount: payment.amount,
+    currency: payment.currency, authorization_code: authorization_code, reference: payment.reference)
+  payment_outcome(client, payment)
+rescue PaystackSdk::ConnectionError, PaystackSdk::ServerError
+  :unknown # Paystack may have charged. Do not send it again: verify payment.reference later (a job).
+end
+```
+
+Do not pass `retry_non_idempotent: true` to `PaystackSdk::Client.new`. It makes the SDK resend writes after a timeout or 5xx (default 2 more times), which can charge twice.
+
+## 4. Reference discipline
+
+- Create the reference and save it on your record **before** the call, so a crash or timeout leaves something to verify.
+- One reference per payment attempt. A failed charge cannot be resumed; the next attempt gets a new reference.
+- Paystack rejects a reference it has already seen: `initiate` and `charge_authorization` with a used reference returned HTTP 400 "Duplicate Transaction Reference" (observed on the test API 2026-10-09). That is a safety net, not a plan: verify first.
+
+## 5. Store the authorization code, never card data
+
+- Store `authorization.authorization_code` (encrypted at rest, for example Rails `encrypts`) and the customer email: `charge_authorization` needs both. Store it only when `authorization.reusable` is true.
+- A verified card transaction returns `authorization_code`, `bin`, `last4`, `exp_month`, `exp_year`, `channel`, `card_type`, `bank`, `country_code`, `brand`, `reusable`, `signature` and `account_name` (observed). `last4`, `brand` and expiry are enough to show the payer which card is saved.
+- Never store or log a card number, CVV, PIN or OTP. They go straight to Paystack.
+
+## 6. Keep secret keys out of logs and error reports
+
+- The SDK puts nothing of the key in its error messages (checked for timeouts, connection failures, 401, 429 and 5xx), nor in `Response#inspect`.
+- **`inspect` and `pp` of a `PaystackSdk::Client`, of any resource (`client.transactions`) and of the connection the SDK builds do not include the secret key** (they print the class name; the connection's `Authorization` header shows `[REDACTED]`). **Versions before 0.4.1 printed the key in full**: on one of those, never log, `pp`, or send to an error reporter a client, a resource or a connection, and rotate the key if you may have. A connection you build yourself and pass to `Client.new(connection)` is yours: its own `inspect` is unchanged. Whatever the version, log the reference, the `Response#error_message` and the HTTP `status_code` instead of whole objects.
+- Read the key from the environment or encrypted credentials; never commit it.
+
+## 7. Key hygiene
+
+- Use `PaystackSdk::Client.new(secret_key: ..., sandbox_only: true)` everywhere except production. It raises `ArgumentError` unless the key starts with `sk_test_`.
+- `client.live?` is true only for an `sk_live_` key. Use it to guard anything that must never run live, and to label logs.
+- `sandbox_only` is a prefix check, not a sandbox. A test key can still reach live mode: the gem documents that `storefronts.publish` copies the storefront and its products to the live integration even with a test key. Do not call such methods from tests or seeds.
+
+## 8. Webhooks
+
+The gem's `PaystackSdk::Webhook` checks the signature (`construct_event`, `valid_signature?`, `verify!`) and the documented sender addresses (`trusted_ip?`). The [[paystack-sdk-webhooks]] skill covers the handler in full. For money safety:
+
+- Verify the signature on the raw body before anything else. The IP check is optional, a second check, never a replacement.
+- Respond `200 OK` fast and do the work in a job. Paystack's webhooks page says unacknowledged events are retried (every 3 minutes for 4 tries, then hourly for 72 hours in live mode; hourly for 10 hours in test mode; 30 second timeout). Documented, not observed.
+- Expect repeats and out-of-order delivery. Paystack documents no event id: dedupe on the event name plus `data.id` or `data.reference`, and in the job call `payment_outcome` (rule 2) instead of trusting the event body.
+- Grant value at most once: make the "paid" transition idempotent (a unique constraint or a row lock on your payment record), because the webhook, the return URL and a verify job can all arrive at the same time.
+
+## 9. Reconciliation
+
+Run a daily job that compares your records with Paystack's. Calls the gem has for it (each answered on the test API; how to match rows is up to you):
+
+| Call | Use it for |
+|---|---|
+| `transactions.list(status:, from:, to:, per_page:, page:)` | Transactions Paystack has, to find ones you never recorded or never granted |
+| `settlements.list(from:, to:)`, `settlements.transactions(id:)` | Payouts to your bank account and the transactions in each |
+| `balances.fetch`, `balances.ledger(from:, to:)` | Your Paystack balance per currency and the entries that moved it |
+
+## Pre-merge checklist
+
+| Check | Pass when |
+|---|---|
+| Amounts | Integers in minor units, converted from a decimal; no Float; no raw `client.connection` call that skips the SDK's check |
+| Reference | Created and saved before the call; one per attempt |
+| Granting value | Only after `transactions.verify` + `paid?(amount:, currency:)` with your stored amount and currency, and the customer email checked |
+| Grant once | The paid transition is idempotent across webhook, return URL and jobs |
+| Writes after timeout | `ConnectionError` / `ServerError` on a write leads to verify by reference, never to a resend |
+| Retries | `retry_non_idempotent` is not set |
+| Webhooks | Signature checked on the raw body; 200 fast; deduped; no value from the event body |
+| Stored data | Only `authorization_code` (encrypted) and display fields; no card number, CVV, PIN or OTP anywhere, including logs |
+| Secrets | Key only from the environment or credentials; `paystack_sdk` >= 0.4.1 (earlier versions printed the key in `inspect`); nothing logs a whole client, resource or connection anyway |
+| Environments | `sandbox_only: true` outside production; nothing that reaches live mode (such as `storefronts.publish`) in tests or seeds |
+| Reconciliation | A scheduled job compares your records with `transactions.list` |
+
+## Not verified
+
+Nothing here ran with a live key. Paystack's accepting `100.0` and `"100"` was seen in test mode only. Whether a resend with the same reference is rejected while the first request is still in flight was not tested. Webhook retry timing and ordering come from Paystack's webhooks page, not from observation. `settlements.list` returned no rows on the test account, so its row shape was not seen.

data/lib/paystack_sdk/skills/paystack-sdk-overview/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: paystack-sdk-overview
+description: 'Use when writing or reviewing Ruby code that calls Paystack through the paystack_sdk gem: creating a client, picking a resource and method, reading a Response, handling errors, or deciding how far to trust a result. Load this first; it covers the conventions every other paystack-sdk skill assumes.'
+---
+
+# paystack_sdk: overview and conventions
+
+`paystack_sdk` is a Ruby client for Paystack's API. It mirrors Paystack's endpoints, does not reshape Paystack's field names, and validates input before sending. This skill was installed from a specific gem version (see `metadata.gem_version` above). If `Gemfile.lock` pins a different version, run `paystack_sdk skills install` (or `rails g paystack_sdk:skills`) again so the skills match the code.
+
+## Set up the client
+
+```ruby
+client = PaystackSdk::Client.new(secret_key: ENV.fetch("PAYSTACK_SECRET_KEY"))
+
+# Staging and CI: refuse anything but a test key, at construction, before any request
+client = PaystackSdk::Client.new(secret_key: ENV.fetch("PAYSTACK_SECRET_KEY"), sandbox_only: true)
+
+client.live? # => true only for a live key (sk_live_...)
+```
+
+- With no `secret_key:` the client reads `PAYSTACK_SECRET_KEY`.
+- `sandbox_only: true` raises `ArgumentError` unless the key starts with `sk_test_`. It checks the key's prefix only. It cannot stop a call that reaches live mode from a test key (publishing a storefront does).
+- Connection options: `timeout` (default 30 s), `open_timeout` (5 s), `max_retries` (2), `retry_interval` (0.5 s). Leave `retry_non_idempotent` off; see "Retries".
+
+## Pick the resource
+
+Each Paystack resource is a method on the client: `transactions`, `charges`, `customers`, `refunds`, `transfers`, `transfer_recipients`, `banks`, `miscellaneous`, `subaccounts`, `splits`, `settlements`, `disputes`, `balances`, `plans`, `subscriptions`, `payment_requests`, `pages`, `products`, `orders`, `storefronts`, `bulk_charges`, `dedicated_virtual_accounts`, `apple_pay`, `integrations`, `virtual_terminals`, `direct_debits`, `terminals`, `webhook_events` (the log of webhooks Paystack sent you; not in Paystack's OpenAPI spec). The signature and a `@see` link to Paystack's docs are in each method's YARD comment in the gem; read them rather than guessing keywords.
+
+## Conventions
+
+- **Keyword arguments, never a payload hash.** `client.transactions.initiate(email: "ama@example.com", amount: 5000)`. To pass a hash you hold, splat it: `initiate(**params)`.
+- **Ruby names are snake_case; Paystack's names go on the wire.** `per_page:` is sent as `perPage`, `next_cursor:` as `next`. Never write Paystack's camelCase names in Ruby calls.
+- **Amounts are integers in the currency's smallest unit** (pesewas, kobo, cents). `5000` is GHS 50.00. Never send a Float.
+- **Path values are escaped.** A blank value raises `PaystackSdk::MissingParamError`, and `.` or `..` raises `PaystackSdk::InvalidValueError`, so a caller cannot redirect a request to another endpoint.
+- **Identifier keywords follow Paystack's docs**: `id_or_code:`, `email_or_code:`, `reference:`. The numeric ID and the string code are not always interchangeable; the method's docs and its topic skill say which.
+
+## Read a Response
+
+Every call returns a `PaystackSdk::Response`.
+
+```ruby
+response = client.transactions.verify(reference: "order-1042")
+
+response.success?          # the call succeeded
+response.status            # a field of Paystack's data, by dot access (raises NoMethodError if the key is absent)
+response.customer.email    # nested fields too
+response[:amount]          # hash-style works with strings or symbols
+response.paid?(amount: 5000, currency: "GHS") # success + status "success" + amount and currency match
+response.status?(:send_pin)                   # compare the "status" field with any value
+response.meta              # pagination: total, page, pageCount, perPage
+response.dig(:authorization, :authorization_code) # nil if any key is missing: use it for optional fields
+response.original_response # the raw body, for anything not wrapped
+response.error_message     # Paystack's message when the call did not succeed
+```
+
+Lists: `response.each` and `first`/`last` give you wrapped rows with dot access (`row.reference`). Enumerable calls such as `map` and `select` pass your block plain **string-keyed Hashes** and return a wrapped result, not an Array. For a plain Array of rows, use `response.original_response["data"]`.
+
+## What raises and what returns
+
+| Situation | What you get |
+|---|---|
+| A required keyword is missing | `ArgumentError` |
+| A value fails validation before sending | a `PaystackSdk::ValidationError` (`MissingParamError`, `InvalidFormatError`, `InvalidValueError`) |
+| 401, bad or missing key | raises `PaystackSdk::AuthenticationError` |
+| 429, rate limited | raises `PaystackSdk::RateLimitError` (`retry_after` when Paystack gives it) |
+| 5xx | raises `PaystackSdk::ServerError` |
+| Any other 4xx (400, 404, 422...) | **returns an unsuccessful `Response`; nothing is raised.** Check `success?` and read `error_message` |
+| Timeout or no connection | raises `PaystackSdk::TimeoutError` or `PaystackSdk::ConnectionError` |
+
+All of these inherit from `PaystackSdk::Error`. The classic bug is calling `.data` on a 400 and treating the result as success. Always branch on `success?`.
+
+## Retries
+
+Reads (GET) retry on network errors and on 429/502/503/504. **Writes retry only on 429**, because a timeout or 5xx on a write may mean Paystack processed it. So after a `TimeoutError` or `ServerError` on a write, do not call it again blindly: look the thing up first (for a payment, `transactions.verify(reference:)`).
+
+## Rules that prevent most bugs
+
+1. **Never give value because of a redirect, a callback or a webhook alone.** Verify by reference: `client.transactions.verify(reference: ref).paid?(amount: expected_amount, currency: "GHS")`. Compare against what you expected to charge, not against what the response says.
+2. **Create and store your own `reference` before you call Paystack**, so you can verify the outcome after a timeout or a crash.
+3. **Branch on `success?` for every call** (see the table above).
+4. **Keep secret keys out of code and logs**, and use `sandbox_only: true` outside production.
+
+## Topic skills: load the one that matches the task
+
+| You are... | Load |
+|---|---|
+| Taking a payment through Paystack's hosted checkout (initiate, redirect, verify) | [[paystack-sdk-payments]] |
+| Reacting to what a Charge API call returns (`send_pin`, `send_otp`, `pay_offline`, `failed`...) | [[paystack-sdk-charge-statuses]] |
+| Charging a mobile money wallet (Ghana: MTN, Telecel, AT Money) | [[paystack-sdk-mobile-money]] |
+| Charging a customer's saved card again (renewals, recurring giving) | [[paystack-sdk-saved-card-renewals]] |
+| Receiving Paystack webhooks | [[paystack-sdk-webhooks]] |
+| Refunding a payment | [[paystack-sdk-refunds]] |
+| Writing tests for code that calls Paystack | [[paystack-sdk-testing]] |
+| Reviewing or writing anything that handles money or keys (apply it before merging payment code) | [[paystack-sdk-money-safety]] |
+
+## What the gem's maintainers have not verified
+
+Nothing has been exercised with a live key. Some operations could not be exercised against Paystack's test API either, and the README marks them "unverified": terminals, dedicated virtual accounts, and the state-changing calls on Apple Pay, integrations, virtual terminals and direct debits. Do not tell a user such a call works; say it follows Paystack's documentation and has not been confirmed. Test mode also does not model everything live mode does (for example, a mobile money charge answers `success` at once in test mode).