manza 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80076371c65341ec2d0505fee01860048e6198a878249315cda749dd66a848e1
+  data.tar.gz: 489435e29915da758541243d8a02af6f94c8ee6cf5c0322341495e89b84eb9b7
+SHA512:
+  metadata.gz: af686049cde39a906d1991c3bdf76b1165963c7a759573dc1f60b60ec1f309c822bb44821eedb4691cdca0fe6db0414662387aec7342f07ab45ddf1c2695bb40
+  data.tar.gz: 720050593b2e7399068b20345d99355cd4ee11547f5e335199e28e6c4b5f03039f9472cbe73b1160b8f5e51ba7ceaf7d584dc89fa41d63e75656a13b4bbac5f7

data/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to `manza` (formerly `zazu-ruby`) are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+The SDK is renamed from Zazu to Manza and released as `manza` 1.0.0.
+The API surface is otherwise unchanged.
+
+### Migration from `zazu-ruby` 0.x
+
+| Was | Now |
+|---|---|
+| `gem "zazu-ruby"` | `gem "manza"` |
+| `require "zazu"` | `require "manza"` |
+| `Zazu.new`, `Zazu::Client`, `Zazu::Error`, … | `Manza.new`, `Manza::Client`, `Manza::Error`, … |
+| `ZAZU_API_KEY` | `MANZA_API_KEY` |
+| `ZAZU_BASE_URL` | `MANZA_BASE_URL` |
+| `ZAZU_API_VERSION` | `MANZA_API_VERSION` |
+| `ZAZU_TIMEOUT` | `MANZA_TIMEOUT` |
+| `Zazu-Version` request header | `Manza-Version` |
+| User-Agent `zazu-ruby/x` | `manza-ruby/x` |
+
+The `ZAZU_*` environment variables keep working for all of 1.x: when
+the `MANZA_*` one is unset, the client reads the old name and prints a
+one-time deprecation warning per variable.
+
+### Changed
+
+- Gem `zazu-ruby` → `manza`, namespace `Zazu` → `Manza`, repository
+  `getmanza/zazu-ruby` → `getmanza/manza-ruby`.
+- Requests send `Manza-Version` and User-Agent `manza-ruby/<version>`.
+- `Response#api_version` reads `Manza-Version`, falling back to
+  `Zazu-Version`.
+- Cassettes use the placeholders `<MANZA_API_KEY>` and `<MANZA_VERSION>`
+  (were `<ZAZU_API_KEY>`, `<ZAZU_VERSION>`). Other SDKs replaying them
+  must rename their placeholders in lockstep.
+- Fixture and staging env vars for recording are `MANZA_FIXTURE_*` and
+  `MANZA_STAGING_*`, with no fallback. Rename them in your `.env`.
+
+## [0.3.0]
+
+### Added
+
+- `Zazu::ConflictError` (409), the 10th error class. A duplicate
+  `client_reference` on a transfer draft raises it with `#payment_id`
+  naming the existing draft. 400 now maps to `Zazu::ValidationError`
+  (lists return 400 for a malformed `limit`/`cursor`).
+- `TransferDrafts#authorize(id, authorization_id:, signature:)` and
+  `#decline(id, authorization_id:, reason: nil)` for machine-authorized
+  transfers. A blank signature raises `Zazu::ArgumentError` locally —
+  the API would count it as a failed attempt.
+- `TransferDrafts#create` documents the new optional `client_reference`;
+  responses carry `client_reference` and `authorization`.
+- `Zazu::TransferAuthorization` — `signature_input`, `sign` and
+  `payee_for`, the HMAC-SHA256 signer for authorization challenges, with
+  a fixed test vector shared across SDKs
+  (`spec/zazu/transfer_authorization_spec.rb`).
+- `Beneficiaries#create`, `#list_external_accounts`,
+  `#get_external_account` and `#create_external_account`.
+- `Zazu::Resources::PayeeTrustRequests` (`zazu.payee_trust_requests`) —
+  `create(external_account_ids:)` and `get(id)`.
+- Docs for new pass-through fields: checkout session `customer_name`,
+  `collect_billing_address`, `billing_address`, `settled_at`,
+  `transaction` and the `clearing` status; payment link billing fields;
+  customer `registration_number` / `vat_number` (and MA-only `tax_id` /
+  `ice_number`).
+
+### Changed
+
+- Default base URL is now `https://ma.manza.finance` (Morocco production;
+  South Africa is `https://za.manza.finance`). Cassettes are recorded
+  against staging at `https://ma.manza.dev`. The old `zazu.ma` hosts are
+  still served.
+- Cassettes scrub `Manza-Version`, `account_number`, `bank_identifier`
+  and the authorize request `signature`. The three authorize cassettes
+  match the request body minus `signature` (`body_without_signature`),
+  which replay cannot reproduce; other SDKs should do the same.
+- `rake fixtures:seed` needs a second, authorizer API key, the
+  authorizer endpoint's signing secret and a tunnel to a local webhook
+  receiver (see the one-time setup in `lib/tasks/fixtures.rake`).
+  Re-recording now executes a real 10.00 MAD transfer (the API minimum).
+- Every cassette is re-recorded against `ma.manza.dev`, including the
+  full machine-authorization path (authorize 200, decline 200, bad
+  signature 422, same key 403, duplicate client_reference 409).
+
+## [0.2.1]
+
+### Added
+
+- `Zazu::Resources::TransferDrafts` — `create` and `get`. Creating a
+  draft routes it into the workspace's in-app approval flow; the API
+  never executes a transfer itself. Lifecycle: `requested` →
+  `processing` → `completed` / `failed`.
+- `Zazu::Resources::Beneficiaries` — `list` and `get`, the read-only
+  recipient directory (each beneficiary embeds its bank accounts;
+  the `default` one is used when a transfer names only the
+  beneficiary_id).
+- Fixture seeding: `discover_beneficiary_id!` + `seed_transfer_draft!`.
+  The transfer_drafts/beneficiaries cassettes in this release are
+  hand-authored against the documented contract; re-record via
+  `rake fixtures:record` once the endpoints are live on staging.
+
+## [0.2.0]
+
+### Added
+
+- `Zazu::Resources::CheckoutSessions` — `create` and `get` for one-off
+  hosted checkout sessions. Status enum: `open`, `processing`,
+  `complete`, `expired` (read-only — no API to mutate). No list, no
+  update, no delete; sessions are addressed by their `cs_…` id.
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- `Zazu::Client` — Faraday + HTTPX adapter, JSON request/response, retry middleware.
+- Resource modules: `Accounts`, `Customers`, `Entity`, `Invoices`, `PaymentLinks`, `WebhookEndpoints`.
+- Cursor-based pagination via `Zazu::Page` (max 100 records per page; no auto-pagination).
+- Error hierarchy: `AuthenticationError`, `ForbiddenError`, `NotFoundError`,
+  `ValidationError`, `RateLimitError`, `ServerError`, `ConnectionError`,
+  `ConfigurationError`, `ArgumentError` — all under `Zazu::Error`.
+- VCR-backed RSpec suite covering every public method.
+- Cassette tarball published as a release asset for cross-language SDK reuse.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manza
+
+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,265 @@
+# Manza Ruby SDK
+
+Ruby SDK for the [Manza API](https://ma.manza.finance). Faraday + HTTPX adapter for HTTP/2 + persistent connections.
+
+```ruby
+gem "manza"
+```
+
+Upgrading from `zazu-ruby` 0.x? See the migration guide in [CHANGELOG.md](CHANGELOG.md).
+
+## Quick start
+
+```ruby
+require "manza"
+
+manza = Manza.new(api_key: ENV["MANZA_API_KEY"])
+# Or with explicit base URL (defaults to https://ma.manza.finance, Morocco):
+manza = Manza.new(api_key: ENV["MANZA_API_KEY"], base_url: "https://za.manza.finance")
+
+entity = manza.entity.get
+# => #<Manza::Response status=200 ...>
+entity.body["name"]
+# => "Acme Corp"
+```
+
+Environment variables `MANZA_API_KEY`, `MANZA_BASE_URL`, `MANZA_API_VERSION`, and `MANZA_TIMEOUT` are read by default. The pre-1.0 `ZAZU_*` names still work for all of 1.x, with a one-time deprecation warning per variable.
+
+## Resources
+
+```ruby
+manza.entity.get
+
+manza.accounts.list(currency_code: "MAD", limit: 50)
+manza.accounts.get("019dde7d-...")
+manza.accounts.list_transactions("019dde7d-...", operation: "credit")
+manza.accounts.get_transaction("019dde7d-...", "01a0e1...")
+
+manza.customers.list(q: "acme")
+manza.customers.get("01a0...")
+manza.customers.create(
+  customer_type: "business",
+  company_name: "Acme Corp",
+  email: "billing@acme.com",
+  ice_number: "000000000000000"
+)
+manza.customers.update("01a0...", email: "new@example.com")
+manza.customers.delete("01a0...")
+
+manza.invoices.list(status: "sent", limit: 50)
+manza.invoices.create(
+  customer_id: "01a0...",
+  currency_code: "MAD",
+  issue_date: "2026-05-03",
+  due_date: "2026-06-03",
+  items: [{ description: "Consulting", quantity: 10, unit_price: "150.00" }]
+)
+manza.invoices.send_invoice("01a0...")
+manza.invoices.mark_as_paid("01a0...")
+manza.invoices.cancel("01a0...")
+manza.invoices.credit_note("01a0...")
+manza.invoices.create_payment_link("01a0...", account_id: "019dde7d-...")
+
+manza.payment_links.list(status: "active")
+manza.payment_links.create(
+  account_id: "019dde7d-...",
+  amount: "1500.00",
+  description: "March consulting",
+  link_type: "single"
+)
+manza.payment_links.cancel("01a0...")
+
+manza.checkout_sessions.create(
+  account_id: "019dde7d-...",
+  amount: "1500.00",
+  success_url: "https://merchant.example.com/success?session_id={CHECKOUT_SESSION_ID}",
+  cancel_url: "https://merchant.example.com/cancel",
+  customer_email: "buyer@example.com",
+  metadata: { order_id: "ORD-123" }
+)
+manza.checkout_sessions.get("cs_...")
+
+manza.beneficiaries.list
+manza.beneficiaries.create(beneficiary_type: "business", company_name: "Acme Supplies", email: "ap@acme.com")
+manza.beneficiaries.list_external_accounts("01a0...")
+manza.beneficiaries.get_external_account("01a0...", "01a1...")
+manza.beneficiaries.create_external_account("01a0...", account_number: "007780...", name: "Main account")
+
+manza.payee_trust_requests.create(external_account_ids: ["01a1..."])
+manza.payee_trust_requests.get("01a2...")
+
+manza.transfer_drafts.create(
+  account_id: "019dde7d-...",
+  beneficiary_id: "01a0...",
+  amount: "2500.00",
+  client_reference: "po_1042" # unique per entity; a duplicate raises Manza::ConflictError
+)
+manza.transfer_drafts.get("01a3...")
+manza.transfer_drafts.decline("01a3...", authorization_id: "01a4...", reason: "Not ours")
+
+manza.webhook_endpoints.list
+manza.webhook_endpoints.create(
+  url: "https://example.com/webhooks/manza",
+  events: ["invoice.sent", "payment_link.paid"]
+)
+manza.webhook_endpoints.test_endpoint("01a0...")
+manza.webhook_endpoints.regenerate_secret("01a0...")
+manza.webhook_endpoints.enable("01a0...")
+manza.webhook_endpoints.disable("01a0...")
+```
+
+## Machine-authorized transfers
+
+A draft inside your entity's authorization envelope (trusted payee, within limits) is sent to your enrolled authorizer endpoint as a `payment.authorization_requested` webhook carrying an `authorization.id` and a one-time `nonce`. Sign the draft from **your own record** of it with the endpoint's signing secret, and authorize it with a **different API key** from the one that created it (the creating key gets 403 `same_key_forbidden`):
+
+```ruby
+input = Manza::TransferAuthorization.signature_input(
+  payment_id: draft["id"],
+  nonce: webhook["data"]["authorization"]["nonce"],
+  amount: draft["amount"],               # the API's decimal string, e.g. "2500.0"
+  currency_code: draft["currency_code"],
+  account_id: draft["account_id"],
+  payee: Manza::TransferAuthorization.payee_for(external_account_id: draft["external_account_id"]),
+  client_reference: draft["client_reference"]
+)
+signature = Manza::TransferAuthorization.sign(secret: signing_secret, signature_input: input)
+
+authorizer = Manza.new(api_key: ENV["MANZA_AUTHORIZER_API_KEY"])
+authorizer.transfer_drafts.authorize(draft["id"], authorization_id: webhook["data"]["authorization"]["id"], signature: signature)
+```
+
+A wrong signature raises `Manza::ValidationError` (`type` `invalid_signature`). Five on one challenge send the draft to your in-app approvers; five in a row suspend the authorizer.
+
+## Pagination
+
+Every list endpoint returns a `Manza::Page`. The SDK enforces a hard cap of **100 records per page** — there is no auto-pagination across pages.
+
+```ruby
+page = manza.invoices.list(limit: 100)
+page.data         # => Array of invoice hashes
+page.has_more     # => true / false
+page.next_cursor  # => string or nil
+
+# Walk pages explicitly:
+while page
+  page.data.each { |inv| process(inv) }
+  page = page.next  # returns nil when has_more is false
+end
+```
+
+For capped iteration, use the underlying `each_page_record` helper on a resource (private; access via `send` if you need it). The deliberate restriction is a guardrail — accidentally pulling 50,000 records in a single SDK call should be impossible without explicit per-page consent.
+
+## Errors
+
+Every non-2xx response raises a subclass of `Manza::Error`:
+
+| Status | Class |
+|---|---|
+| 401 | `Manza::AuthenticationError` |
+| 403 | `Manza::ForbiddenError` |
+| 400 | `Manza::ValidationError` (malformed request, e.g. bad `limit`/`cursor`) |
+| 404 | `Manza::NotFoundError` |
+| 409 | `Manza::ConflictError` (carries `#payment_id` for a duplicate `client_reference`) |
+| 422 | `Manza::ValidationError` |
+| 429 | `Manza::RateLimitError` (carries `#retry_after`) |
+| 5xx | `Manza::ServerError` |
+| network | `Manza::ConnectionError` |
+
+Each error exposes `#status`, `#request_id`, `#type`, `#param`, and the raw `#body`.
+
+```ruby
+begin
+  manza.invoices.get("does-not-exist")
+rescue Manza::NotFoundError => e
+  e.status      # => 404
+  e.request_id  # => "req_..."
+  e.type        # => "not_found_error"
+end
+```
+
+## Versioning the API contract
+
+```ruby
+manza = Manza.new(api_key: "...", api_version: "2026-03-27")
+```
+
+Or via env: `MANZA_API_VERSION=2026-03-27`. The header is sent on every request; the API echoes it back in `Manza-Version` (and the legacy `Zazu-Version`); `response.api_version` reads it.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+The spec suite is VCR-backed — cassettes live in `spec/fixtures/cassettes/` and are committed to the repo.
+
+To re-record cassettes against staging:
+
+```bash
+cp .env.example .env
+# fill in the keys, MANZA_FIXTURE_ACCOUNT_ID and MANZA_FIXTURE_BENEFICIARY_ID
+cloudflared tunnel --config ~/.cloudflared/zazu-sdk-authorizer.yml run zazu-sdk-authorizer   # separate terminal
+bundle exec rake fixtures:record
+```
+
+Recording executes a real 10.00 MAD transfer on staging (the authorize cassette). The one-time staging setup (keys, authorizer enrolment, trusted payee) is listed at the top of `lib/tasks/fixtures.rake`.
+
+### The authorizer tunnel
+
+The machine-authorization cassettes need the `payment.authorization_requested` webhook, which staging sends to the webhook endpoint enrolled as transfer authorizer. During `rake fixtures:record` the seeder listens for it on `127.0.0.1:${MANZA_STAGING_AUTHORIZER_PORT:-4599}`, so a tunnel must forward the endpoint's public URL to that port. The endpoint URL cannot change once enrolled, so the tunnel needs a **stable hostname** (a throwaway `trycloudflare.com` URL won't do).
+
+The existing setup uses a named Cloudflare tunnel `zazu-sdk-authorizer` → `https://sdk-authorizer.manza.dev/`. To run it on a new machine:
+
+```bash
+brew install cloudflared
+cloudflared tunnel login                    # pick the manza.dev zone
+cloudflared tunnel token --cred-file ~/.cloudflared/zazu-sdk-authorizer.json zazu-sdk-authorizer
+cat > ~/.cloudflared/zazu-sdk-authorizer.yml <<YML
+tunnel: zazu-sdk-authorizer
+credentials-file: $HOME/.cloudflared/zazu-sdk-authorizer.json
+ingress:
+  - hostname: sdk-authorizer.manza.dev
+    service: http://127.0.0.1:4599
+  - service: http_status:404
+YML
+cloudflared tunnel --config ~/.cloudflared/zazu-sdk-authorizer.yml run zazu-sdk-authorizer
+```
+
+To create one from scratch instead (then point a new webhook endpoint at it and enrol that one as authorizer):
+
+```bash
+cloudflared tunnel create zazu-sdk-authorizer
+cloudflared tunnel route dns zazu-sdk-authorizer sdk-authorizer.manza.dev
+```
+
+The tunnel's `service` port must match `MANZA_STAGING_AUTHORIZER_PORT`: if you change one, change the other, or deliveries never reach the seeder and `fixtures:record` times out waiting for them.
+
+Check it end to end: with the tunnel running and nothing on port 4599, `curl -X POST https://sdk-authorizer.manza.dev/` returns 502. During a record run the seeder answers unsigned requests with 401.
+
+Cassettes are scrubbed before write — bearer tokens and request IDs are rewritten to placeholders. Even if a real key is in `.env`, the committed cassette never contains it.
+
+## Cassettes for other-language SDKs
+
+Each release of `manza-ruby` publishes the cassette directory as a tarball release asset:
+
+```
+https://github.com/getmanza/manza-ruby/releases/download/v0.1.0/cassettes-v0.1.0.tar.gz
+```
+
+`manza-go`, `manza-python`, etc. pin a specific tag in their cassette fetch script and download the tarball during CI. This guarantees every SDK is tested against the same recorded API interactions, surfacing cross-SDK inconsistencies immediately.
+
+VCR's YAML format is supported natively by:
+
+- Ruby — VCR (this gem)
+- Go — go-vcr
+- Python — VCR.py
+- PHP — PHP-VCR
+- Crystal — vcr-crystal / hi8.cr
+- Rust — http_replayer (or a small custom YAML reader)
+- JavaScript / TypeScript — Talkback or polly.js (slight format adapter needed)
+
+## License
+
+MIT

data/lib/manza/client.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "httpx/adapters/faraday"
+require "json"
+require "securerandom"
+
+module Manza
+  # The main SDK entry point.
+  #
+  #   manza = Manza::Client.new(api_key: "sk_live_...")
+  #   manza.entity.get
+  #   manza.accounts.list(limit: 50)
+  #
+  # All public state is set at construction time. The client is
+  # thread-safe in the sense that the underlying Faraday connection
+  # uses a connection pool via the HTTPX adapter — multiple threads
+  # can share one client.
+  class Client
+    # Morocco production. South Africa: https://za.manza.finance.
+    DEFAULT_BASE_URL = "https://ma.manza.finance"
+    DEFAULT_TIMEOUT = 30
+    USER_AGENT = "manza-ruby/#{VERSION}".freeze
+
+    attr_reader :api_key, :base_url, :api_version, :timeout, :logger
+
+    # Reads MANZA_<name>, falling back to the pre-1.0 ZAZU_<name> with a
+    # one-time deprecation warning per variable. The fallback stays for
+    # all of 1.x.
+    #
+    # @api private
+    def self.env(name)
+      value = ENV.fetch("MANZA_#{name}", nil)
+      return value unless value.nil?
+
+      legacy = ENV.fetch("ZAZU_#{name}", nil)
+      return if legacy.nil?
+
+      @warned_legacy_env ||= Set.new
+      warn("[manza] ZAZU_#{name} is deprecated; set MANZA_#{name} instead.") if @warned_legacy_env.add?(name)
+      legacy
+    end
+
+    def initialize(
+      api_key: Client.env("API_KEY"),
+      base_url: Client.env("BASE_URL") || DEFAULT_BASE_URL,
+      api_version: Client.env("API_VERSION"),
+      timeout: Integer(Client.env("TIMEOUT") || DEFAULT_TIMEOUT),
+      logger: nil
+    )
+      raise ConfigurationError, "Missing api_key. Pass api_key: or set MANZA_API_KEY." if api_key.to_s.empty?
+
+      @api_key = api_key
+      @base_url = base_url.to_s.chomp("/")
+      @api_version = api_version
+      @timeout = timeout
+      @logger = logger
+    end
+
+    # Resource accessors — each returns a memoized resource module.
+    def accounts
+      @accounts ||= Resources::Accounts.new(self)
+    end
+
+    def beneficiaries
+      @beneficiaries ||= Resources::Beneficiaries.new(self)
+    end
+
+    def checkout_sessions
+      @checkout_sessions ||= Resources::CheckoutSessions.new(self)
+    end
+
+    def customers
+      @customers ||= Resources::Customers.new(self)
+    end
+
+    def entity
+      @entity ||= Resources::Entity.new(self)
+    end
+
+    def invoices
+      @invoices ||= Resources::Invoices.new(self)
+    end
+
+    def payment_links
+      @payment_links ||= Resources::PaymentLinks.new(self)
+    end
+
+    def payee_trust_requests
+      @payee_trust_requests ||= Resources::PayeeTrustRequests.new(self)
+    end
+
+    def transfer_drafts
+      @transfer_drafts ||= Resources::TransferDrafts.new(self)
+    end
+
+    def webhook_endpoints
+      @webhook_endpoints ||= Resources::WebhookEndpoints.new(self)
+    end
+
+    # Performs an HTTP request and returns a {Manza::Response} on
+    # success. Translates non-2xx responses into the matching
+    # {Manza::Error} subclass.
+    def request(method, path, params: nil, body: nil, headers: {})
+      raw = connection.send(method) do |req|
+        req.url(path)
+        req.params.update(params) if params
+        req.body = body unless body.nil?
+        headers.each { |k, v| req.headers[k] = v }
+      end
+
+      response = Response.new(raw)
+      return response if response.success?
+
+      raise build_error(response)
+    rescue Faraday::TimeoutError => e
+      raise ConnectionError, "Request timed out after #{timeout}s: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |f|
+        f.headers["Authorization"] = "Bearer #{api_key}"
+        f.headers["User-Agent"] = USER_AGENT
+        f.headers["Accept"] = "application/json"
+        f.headers["Manza-Version"] = api_version if api_version
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.options.timeout = timeout
+        f.options.open_timeout = [timeout, 10].min
+        f.response :logger, logger if logger
+        f.adapter(*adapter_args)
+      end
+    end
+
+    # The HTTPX adapter ships its own WebMock plugin that wraps every
+    # connection. When VCR's WebMock library hook is also active and
+    # net-connect is allowed (recording mode), the two interceptors
+    # layer in a way that deadlocks on the first real request. For
+    # cassette recording we drop down to Net::HTTP, which has rock-
+    # solid WebMock + VCR integration. Cassettes are adapter-agnostic
+    # so replay continues to use the production HTTPX adapter.
+    def adapter_args
+      ENV["VCR_RECORD"] ? [:net_http] : [:httpx]
+    end
+
+    # Lookup table for status → (error class, default message). 5xx
+    # is matched separately because Range keys don't work in Hash
+    # lookup the way exact integers do.
+    ERROR_BY_STATUS = {
+      400 => [ValidationError, "Bad request"],
+      401 => [AuthenticationError, "Authentication failed"],
+      403 => [ForbiddenError, "Forbidden"],
+      404 => [NotFoundError, "Not found"],
+      422 => [ValidationError, "Validation failed"]
+    }.freeze
+    private_constant :ERROR_BY_STATUS
+
+    def build_error(response)
+      payload = error_payload(response.body)
+      message = payload["message"]
+      kwargs = error_kwargs(response, payload)
+
+      if (mapping = ERROR_BY_STATUS[response.status])
+        klass, default_message = mapping
+        return klass.new(message || default_message, **kwargs)
+      end
+
+      build_special_error(response, payload, message, kwargs)
+    end
+
+    def error_payload(body)
+      return {} unless body.is_a?(Hash) && body["error"].is_a?(Hash)
+
+      body["error"]
+    end
+
+    def error_kwargs(response, payload)
+      {
+        status: response.status,
+        request_id: response.request_id,
+        type: payload["type"],
+        param: payload["param"],
+        body: response.body
+      }
+    end
+
+    def build_special_error(response, payload, message, kwargs)
+      case response.status
+      when 409
+        ConflictError.new(message || "Conflict", payment_id: payload["payment_id"], **kwargs)
+      when 429
+        retry_after = response.headers["retry-after"]&.to_i
+        RateLimitError.new(message || "Rate limited", retry_after: retry_after, **kwargs)
+      when 500..599
+        ServerError.new(message || "Server error (#{response.status})", **kwargs)
+      else
+        Error.new(message || "Unexpected status #{response.status}", **kwargs)
+      end
+    end
+  end
+end