pushpay-ruby 0.2.0

data/lib/pushpay/organization.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Organization < Base
+    # Get a specific organization
+    def find(organization_key)
+      client.get("/v1/organization/#{organization_key}")
+    end
+
+    # Search organizations
+    def search(**params)
+      client.get("/v1/organizations", params)
+    end
+
+    # List organizations accessible to the current application
+    def in_scope(**params)
+      client.get("/v1/organizations/in-scope", params)
+    end
+
+    # List campuses for an organization
+    def campuses(organization_key: nil, **params)
+      client.get("#{organization_path(organization_key)}/campuses", params)
+    end
+
+    # List merchant listings for an organization
+    def merchant_listings(organization_key: nil, **params)
+      client.get("#{organization_path(organization_key)}/merchantlistings", params)
+    end
+  end
+end

data/lib/pushpay/payment.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Payment < Base
+    # Get a single payment by token
+    def find(payment_token, merchant_key: nil)
+      client.get("#{merchant_path(merchant_key)}/payment/#{payment_token}")
+    end
+
+    # List payments for a merchant
+    def list(merchant_key: nil, **params)
+      client.get("#{merchant_path(merchant_key)}/payments", params)
+    end
+
+    # List payments across an organization
+    def list_for_organization(organization_key: nil, **params)
+      client.get("#{organization_path(organization_key)}/payments", params)
+    end
+  end
+end

data/lib/pushpay/recurring_payment.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PushPay
+  class RecurringPayment < Base
+    # Get a single recurring payment by token
+    def find(payment_token, merchant_key: nil)
+      client.get("#{merchant_path(merchant_key)}/recurringpayment/#{payment_token}")
+    end
+
+    # List recurring payments for a merchant
+    def list(merchant_key: nil, **params)
+      client.get("#{merchant_path(merchant_key)}/recurringpayments", params)
+    end
+
+    # List recurring payments across an organization
+    def list_for_organization(organization_key: nil, **params)
+      client.get("#{organization_path(organization_key)}/recurringpayments", params)
+    end
+
+    # List payments linked to a recurring payment schedule
+    def payments(payment_token, merchant_key: nil, **params)
+      client.get("#{merchant_path(merchant_key)}/recurringpayment/#{payment_token}/payments", params)
+    end
+  end
+end

data/lib/pushpay/settlement.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Settlement < Base
+    # Get a specific settlement
+    def find(settlement_key)
+      client.get("/v1/settlement/#{settlement_key}")
+    end
+
+    # List settlements for a merchant
+    def list(merchant_key: nil, **params)
+      client.get("#{merchant_path(merchant_key)}/settlements", params)
+    end
+
+    # List settlements for an organization
+    def list_for_organization(organization_key: nil, **params)
+      client.get("#{organization_path(organization_key)}/settlements", params)
+    end
+
+    # Get payments within a settlement
+    def payments(settlement_key, **params)
+      client.get("/v1/settlement/#{settlement_key}/payments", params)
+    end
+  end
+end

data/lib/pushpay/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PushPay
+  VERSION = "0.2.0"
+end

data/lib/pushpay/webhook.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Webhook < Base
+    # Get a specific webhook
+    def find(webhook_token, merchant_key: nil)
+      client.get("#{merchant_path(merchant_key)}/webhook/#{webhook_token}")
+    end
+
+    # List webhooks for a merchant
+    def list(merchant_key: nil, **params)
+      client.get("#{merchant_path(merchant_key)}/webhooks", params)
+    end
+
+    # Create a webhook
+    def create(params, merchant_key: nil)
+      client.post("#{merchant_path(merchant_key)}/webhooks", params)
+    end
+
+    # Update a webhook
+    def update(webhook_token, params, merchant_key: nil)
+      client.put("#{merchant_path(merchant_key)}/webhook/#{webhook_token}", params)
+    end
+
+    # Delete a webhook
+    def delete(webhook_token, merchant_key: nil)
+      client.delete("#{merchant_path(merchant_key)}/webhook/#{webhook_token}")
+    end
+  end
+end

data/lib/pushpay.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'json'
+
+require_relative 'pushpay/version'
+require_relative 'pushpay/errors'
+require_relative 'pushpay/configuration'
+require_relative 'pushpay/client'
+require_relative 'pushpay/base'
+require_relative 'pushpay/payment'
+require_relative 'pushpay/recurring_payment'
+require_relative 'pushpay/anticipated_payment'
+require_relative 'pushpay/merchant'
+require_relative 'pushpay/organization'
+require_relative 'pushpay/fund'
+require_relative 'pushpay/settlement'
+require_relative 'pushpay/batch'
+require_relative 'pushpay/webhook'
+
+module PushPay
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    def reset!
+      @client = nil
+      @configuration = nil
+    end
+  end
+end

data/spec/examples.txt

@@ -0,0 +1,63 @@
+example_id                                        | status | run_time        |
+------------------------------------------------- | ------ | --------------- |
+./spec/pushpay/anticipated_payment_spec.rb[1:1:1] | passed | 0.00053 seconds |
+./spec/pushpay/anticipated_payment_spec.rb[1:2:1] | passed | 0.00041 seconds |
+./spec/pushpay/batch_spec.rb[1:1:1]               | passed | 0.00046 seconds |
+./spec/pushpay/batch_spec.rb[1:2:1]               | passed | 0.0005 seconds  |
+./spec/pushpay/batch_spec.rb[1:3:1]               | passed | 0.00047 seconds |
+./spec/pushpay/client_spec.rb[1:1:1]              | passed | 0.00034 seconds |
+./spec/pushpay/client_spec.rb[1:1:2:1]            | passed | 0.00012 seconds |
+./spec/pushpay/client_spec.rb[1:2:1]              | passed | 0.00031 seconds |
+./spec/pushpay/client_spec.rb[1:2:2]              | passed | 0.00026 seconds |
+./spec/pushpay/client_spec.rb[1:2:3]              | passed | 0.00074 seconds |
+./spec/pushpay/client_spec.rb[1:2:4]              | passed | 0.00079 seconds |
+./spec/pushpay/client_spec.rb[1:2:5]              | passed | 0.00027 seconds |
+./spec/pushpay/client_spec.rb[1:2:6]              | passed | 0.0003 seconds  |
+./spec/pushpay/client_spec.rb[1:3:1]              | passed | 0.00038 seconds |
+./spec/pushpay/client_spec.rb[1:3:2]              | passed | 0.00056 seconds |
+./spec/pushpay/client_spec.rb[1:3:3]              | passed | 0.00192 seconds |
+./spec/pushpay/client_spec.rb[1:4:1]              | passed | 0.0004 seconds  |
+./spec/pushpay/client_spec.rb[1:5:1]              | passed | 0.0004 seconds  |
+./spec/pushpay/client_spec.rb[1:6:1]              | passed | 0.00044 seconds |
+./spec/pushpay/client_spec.rb[1:7:1]              | passed | 0.00044 seconds |
+./spec/pushpay/client_spec.rb[1:7:2]              | passed | 0.00045 seconds |
+./spec/pushpay/client_spec.rb[1:7:3]              | passed | 0.00141 seconds |
+./spec/pushpay/client_spec.rb[1:7:4]              | passed | 0.00054 seconds |
+./spec/pushpay/client_spec.rb[1:7:5]              | passed | 0.00044 seconds |
+./spec/pushpay/configuration_spec.rb[1:1:1]       | passed | 0.00006 seconds |
+./spec/pushpay/configuration_spec.rb[1:2:1]       | passed | 0.00006 seconds |
+./spec/pushpay/configuration_spec.rb[1:3:1]       | passed | 0.00006 seconds |
+./spec/pushpay/configuration_spec.rb[1:3:2]       | passed | 0.00035 seconds |
+./spec/pushpay/configuration_spec.rb[1:3:3]       | passed | 0.00006 seconds |
+./spec/pushpay/configuration_spec.rb[1:3:4]       | passed | 0.00006 seconds |
+./spec/pushpay/configuration_spec.rb[1:4:1]       | passed | 0.00068 seconds |
+./spec/pushpay/configuration_spec.rb[1:4:2]       | passed | 0.00056 seconds |
+./spec/pushpay/configuration_spec.rb[1:4:3]       | passed | 0.00007 seconds |
+./spec/pushpay/fund_spec.rb[1:1:1]                | passed | 0.00052 seconds |
+./spec/pushpay/fund_spec.rb[1:2:1]                | passed | 0.00052 seconds |
+./spec/pushpay/fund_spec.rb[1:3:1]                | passed | 0.00051 seconds |
+./spec/pushpay/fund_spec.rb[1:4:1]                | passed | 0.00057 seconds |
+./spec/pushpay/fund_spec.rb[1:5:1]                | passed | 0.00043 seconds |
+./spec/pushpay/merchant_spec.rb[1:1:1]            | passed | 0.00046 seconds |
+./spec/pushpay/merchant_spec.rb[1:2:1]            | passed | 0.0005 seconds  |
+./spec/pushpay/merchant_spec.rb[1:3:1]            | passed | 0.00047 seconds |
+./spec/pushpay/merchant_spec.rb[1:4:1]            | passed | 0.00074 seconds |
+./spec/pushpay/organization_spec.rb[1:1:1]        | passed | 0.00054 seconds |
+./spec/pushpay/organization_spec.rb[1:2:1]        | passed | 0.00044 seconds |
+./spec/pushpay/organization_spec.rb[1:3:1]        | passed | 0.00052 seconds |
+./spec/pushpay/payment_spec.rb[1:1:1]             | passed | 0.00062 seconds |
+./spec/pushpay/payment_spec.rb[1:1:2]             | passed | 0.00124 seconds |
+./spec/pushpay/payment_spec.rb[1:2:1]             | passed | 0.00048 seconds |
+./spec/pushpay/payment_spec.rb[1:2:2]             | passed | 0.00063 seconds |
+./spec/pushpay/payment_spec.rb[1:3:1]             | passed | 0.00047 seconds |
+./spec/pushpay/recurring_payment_spec.rb[1:1:1]   | passed | 0.00047 seconds |
+./spec/pushpay/recurring_payment_spec.rb[1:2:1]   | passed | 0.00098 seconds |
+./spec/pushpay/recurring_payment_spec.rb[1:3:1]   | passed | 0.00049 seconds |
+./spec/pushpay/settlement_spec.rb[1:1:1]          | passed | 0.00165 seconds |
+./spec/pushpay/settlement_spec.rb[1:2:1]          | passed | 0.00048 seconds |
+./spec/pushpay/settlement_spec.rb[1:3:1]          | passed | 0.0006 seconds  |
+./spec/pushpay/webhook_spec.rb[1:1:1]             | passed | 0.00048 seconds |
+./spec/pushpay/webhook_spec.rb[1:2:1]             | passed | 0.00085 seconds |
+./spec/pushpay/webhook_spec.rb[1:3:1]             | passed | 0.00048 seconds |
+./spec/pushpay/webhook_spec.rb[1:4:1]             | passed | 0.01884 seconds |
+./spec/pushpay/webhook_spec.rb[1:5:1]             | passed | 0.00042 seconds |

data/spec/pushpay/anticipated_payment_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe PushPay::AnticipatedPayment do
+  let(:anticipated) { described_class.new(PushPay.client) }
+  let(:base_url) { "https://api.pushpay.io" }
+
+  describe "#create" do
+    it "creates an anticipated payment" do
+      stub_request(:post, "#{base_url}/v1/merchant/test_merchant_key/anticipatedpayments")
+        .with(body: { amount: "50.00" }.to_json)
+        .to_return(status: 201, body: { status: "Unassociated" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = anticipated.create({ amount: "50.00" })
+      expect(result["status"]).to eq("Unassociated")
+    end
+  end
+
+  describe "#list" do
+    it "lists anticipated payments" do
+      stub_request(:get, "#{base_url}/v1/merchant/test_merchant_key/anticipatedpayments")
+        .to_return(status: 200, body: { items: [] }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = anticipated.list
+      expect(result["items"]).to eq([])
+    end
+  end
+end

data/spec/pushpay/batch_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe PushPay::Batch do
+  let(:batches) { described_class.new(PushPay.client) }
+  let(:base_url) { "https://api.pushpay.io" }
+
+  describe "#find" do
+    it "gets a batch by key" do
+      stub_request(:get, "#{base_url}/v1/merchant/test_merchant_key/batch/batch_123")
+        .to_return(status: 200, body: { key: "batch_123", name: "March Batch" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = batches.find("batch_123")
+      expect(result["name"]).to eq("March Batch")
+    end
+  end
+
+  describe "#list" do
+    it "lists batches for a merchant" do
+      stub_request(:get, "#{base_url}/v1/merchant/test_merchant_key/batches")
+        .to_return(status: 200, body: { items: [] }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = batches.list
+      expect(result["items"]).to eq([])
+    end
+  end
+
+  describe "#payments" do
+    it "lists payments within a batch" do
+      stub_request(:get, "#{base_url}/v1/merchant/test_merchant_key/batch/batch_123/payments")
+        .to_return(status: 200, body: { items: [] }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = batches.payments("batch_123")
+      expect(result["items"]).to eq([])
+    end
+  end
+end

data/spec/pushpay/client_spec.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "base64"
+
+RSpec.describe PushPay::Client do
+  let(:client) { PushPay.client }
+
+  describe "#initialize" do
+    it "creates a client instance" do
+      expect(client).to be_a(described_class)
+    end
+
+    context "with missing credentials" do
+      it "raises a ConfigurationError" do
+        config = PushPay::Configuration.new
+        expect { described_class.new(config) }.to raise_error(PushPay::ConfigurationError)
+      end
+    end
+  end
+
+  describe "#authenticate!" do
+    it "sends Basic auth header with base64 encoded credentials" do
+      client.authenticate!
+
+      expected_auth = Base64.strict_encode64("test_client_id:test_client_secret")
+      expect(WebMock).to have_requested(:post, "https://auth.pushpay.com/pushpay/oauth/token")
+        .with(headers: { "Authorization" => "Basic #{expected_auth}" })
+    end
+
+    it "sets access_token from response" do
+      client.authenticate!
+      expect(client.access_token).to eq("test_token")
+    end
+
+    it "sets token expiration" do
+      client.authenticate!
+      expect(client.token_expires_at).to be > Time.now
+    end
+
+    it "raises AuthenticationError on failure" do
+      stub_request(:post, "https://auth.pushpay.com/pushpay/oauth/token")
+        .to_return(status: 401, body: "Unauthorized")
+
+      expect { client.authenticate! }.to raise_error(PushPay::AuthenticationError)
+    end
+
+    it "sends read scope by default" do
+      client.authenticate!
+
+      expect(WebMock).to have_requested(:post, "https://auth.pushpay.com/pushpay/oauth/token")
+        .with(body: hash_including(scope: "read"))
+    end
+
+    it "includes custom scopes when configured" do
+      PushPay.configuration.scopes = %w[read merchant:view_payments]
+      client.authenticate!
+
+      expect(WebMock).to have_requested(:post, "https://auth.pushpay.com/pushpay/oauth/token")
+        .with(body: hash_including(scope: "read merchant:view_payments"))
+    end
+  end
+
+  describe "#get" do
+    it "makes authenticated GET request" do
+      stub_request(:get, "https://api.pushpay.io/v1/test")
+        .to_return(status: 200, body: { data: "ok" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = client.get("/v1/test")
+      expect(result).to eq("data" => "ok")
+    end
+
+    it "sends Accept: application/hal+json header" do
+      stub_request(:get, "https://api.pushpay.io/v1/test")
+        .to_return(status: 200, body: {}.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      client.get("/v1/test")
+      expect(WebMock).to have_requested(:get, "https://api.pushpay.io/v1/test")
+        .with(headers: { "Accept" => "application/hal+json" })
+    end
+
+    it "passes query parameters" do
+      stub_request(:get, "https://api.pushpay.io/v1/test")
+        .with(query: { page: "0", pageSize: "25" })
+        .to_return(status: 200, body: {}.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      client.get("/v1/test", page: "0", pageSize: "25")
+    end
+  end
+
+  describe "#post" do
+    it "makes authenticated POST request with JSON body" do
+      stub_request(:post, "https://api.pushpay.io/v1/test")
+        .with(body: { name: "test" }.to_json,
+              headers: { "Content-Type" => "application/json" })
+        .to_return(status: 201, body: { id: "123" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = client.post("/v1/test", name: "test")
+      expect(result).to eq("id" => "123")
+    end
+  end
+
+  describe "#put" do
+    it "makes authenticated PUT request" do
+      stub_request(:put, "https://api.pushpay.io/v1/test")
+        .to_return(status: 200, body: { success: true }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = client.put("/v1/test", name: "updated")
+      expect(result).to eq("success" => true)
+    end
+  end
+
+  describe "#delete" do
+    it "makes authenticated DELETE request" do
+      stub_request(:delete, "https://api.pushpay.io/v1/test")
+        .to_return(status: 204, body: nil)
+
+      client.delete("/v1/test")
+    end
+  end
+
+  describe "error handling" do
+    it "raises AuthenticationError on 401 and clears token" do
+      stub_request(:get, "https://api.pushpay.io/v1/expired")
+        .to_return(status: 401, body: "Unauthorized")
+
+      expect { client.get("/v1/expired") }.to raise_error(PushPay::AuthenticationError)
+      expect(client.access_token).to be_nil
+    end
+
+    it "raises NotFoundError on 404" do
+      stub_request(:get, "https://api.pushpay.io/v1/missing")
+        .to_return(status: 404, body: "Not Found")
+
+      expect { client.get("/v1/missing") }.to raise_error(PushPay::NotFoundError)
+    end
+
+    it "raises RateLimitError on 429 with retry-after" do
+      stub_request(:get, "https://api.pushpay.io/v1/limited")
+        .to_return(status: 429, body: "Too Many Requests",
+                   headers: { "retry-after" => "30" })
+
+      expect { client.get("/v1/limited") }.to raise_error(PushPay::RateLimitError) do |error|
+        expect(error.retry_after).to eq("30")
+      end
+    end
+
+    it "raises ValidationError on 400 with validation failures" do
+      stub_request(:post, "https://api.pushpay.io/v1/bad")
+        .to_return(
+          status: 400,
+          body: { message: "Bad Request", validationFailures: { "name" => ["is required"] } }.to_json,
+          headers: { "Content-Type" => "application/json" }
+        )
+
+      expect { client.post("/v1/bad", {}) }.to raise_error(PushPay::ValidationError) do |error|
+        expect(error.errors).to eq("name" => ["is required"])
+      end
+    end
+
+    it "raises APIError on 500" do
+      stub_request(:get, "https://api.pushpay.io/v1/error")
+        .to_return(status: 500, body: "Internal Server Error")
+
+      expect { client.get("/v1/error") }.to raise_error(PushPay::APIError)
+    end
+  end
+end

data/spec/pushpay/configuration_spec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe PushPay::Configuration do
+  let(:config) { described_class.new }
+
+  describe "#initialize" do
+    it "sets default values" do
+      expect(config.base_url).to eq("https://api.pushpay.io")
+      expect(config.auth_url).to eq("https://auth.pushpay.com/pushpay/oauth/token")
+      expect(config.timeout).to eq(30)
+      expect(config.scopes).to eq(["read"])
+    end
+  end
+
+  describe "#sandbox!" do
+    it "sets sandbox URLs" do
+      config.sandbox!
+      expect(config.base_url).to eq("https://sandbox-api.pushpay.io")
+      expect(config.auth_url).to eq("https://auth.pushpay.com/pushpay-sandbox/oauth/token")
+    end
+  end
+
+  describe "#valid?" do
+    it "returns true when both credentials are present" do
+      config.client_id = "id"
+      config.client_secret = "secret"
+      expect(config.valid?).to be true
+    end
+
+    it "returns false when client_id is missing" do
+      config.client_secret = "secret"
+      expect(config.valid?).to be false
+    end
+
+    it "returns false when client_secret is missing" do
+      config.client_id = "id"
+      expect(config.valid?).to be false
+    end
+
+    it "returns false with empty strings" do
+      config.client_id = ""
+      config.client_secret = ""
+      expect(config.valid?).to be false
+    end
+  end
+
+  describe "#missing_credentials" do
+    it "returns all missing fields when none set" do
+      expect(config.missing_credentials).to contain_exactly("client_id", "client_secret")
+    end
+
+    it "returns empty array when all present" do
+      config.client_id = "id"
+      config.client_secret = "secret"
+      expect(config.missing_credentials).to be_empty
+    end
+
+    it "returns only missing fields" do
+      config.client_id = "id"
+      expect(config.missing_credentials).to contain_exactly("client_secret")
+    end
+  end
+end

data/spec/pushpay/fund_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe PushPay::Fund do
+  let(:funds) { described_class.new(PushPay.client) }
+  let(:base_url) { "https://api.pushpay.io" }
+
+  describe "#find" do
+    it "gets a fund by key" do
+      stub_request(:get, "#{base_url}/v1/organization/test_org_key/fund/fund_123")
+        .to_return(status: 200, body: { key: "fund_123", name: "General" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = funds.find("fund_123")
+      expect(result["name"]).to eq("General")
+    end
+  end
+
+  describe "#list" do
+    it "lists funds for a merchant" do
+      stub_request(:get, "#{base_url}/v1/merchant/test_merchant_key/funds")
+        .to_return(status: 200, body: { items: [] }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = funds.list
+      expect(result["items"]).to eq([])
+    end
+  end
+
+  describe "#create" do
+    it "creates a fund" do
+      stub_request(:post, "#{base_url}/v1/organization/test_org_key/funds")
+        .with(body: { name: "Missions", taxDeductible: true }.to_json)
+        .to_return(status: 201, body: { key: "fund_new", name: "Missions" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = funds.create({ name: "Missions", taxDeductible: true })
+      expect(result["name"]).to eq("Missions")
+    end
+  end
+
+  describe "#update" do
+    it "updates a fund" do
+      stub_request(:put, "#{base_url}/v1/organization/test_org_key/fund/fund_123")
+        .to_return(status: 200, body: { key: "fund_123", name: "Updated" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = funds.update("fund_123", { name: "Updated" })
+      expect(result["name"]).to eq("Updated")
+    end
+  end
+
+  describe "#delete" do
+    it "deletes a fund" do
+      stub_request(:delete, "#{base_url}/v1/organization/test_org_key/fund/fund_123")
+        .to_return(status: 204, body: nil)
+
+      funds.delete("fund_123")
+    end
+  end
+end

data/spec/pushpay/merchant_spec.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe PushPay::Merchant do
+  let(:merchants) { described_class.new(PushPay.client) }
+  let(:base_url) { "https://api.pushpay.io" }
+
+  describe "#find" do
+    it "gets a merchant by key" do
+      stub_request(:get, "#{base_url}/v1/merchant/mk_123")
+        .to_return(status: 200, body: { key: "mk_123", name: "Test Church" }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = merchants.find("mk_123")
+      expect(result["name"]).to eq("Test Church")
+    end
+  end
+
+  describe "#search" do
+    it "searches merchants by name" do
+      stub_request(:get, "#{base_url}/v1/merchants")
+        .with(query: { name: "Test" })
+        .to_return(status: 200, body: { items: [] }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = merchants.search(name: "Test")
+      expect(result["items"]).to eq([])
+    end
+  end
+
+  describe "#in_scope" do
+    it "lists accessible merchants" do
+      stub_request(:get, "#{base_url}/v1/merchants/in-scope")
+        .to_return(status: 200, body: { items: [] }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = merchants.in_scope
+      expect(result["items"]).to eq([])
+    end
+  end
+
+  describe "#near" do
+    it "searches nearby merchants" do
+      stub_request(:get, "#{base_url}/v1/merchants/near")
+        .with(query: { latitude: "37.7749", longitude: "-122.4194", country: "US" })
+        .to_return(status: 200, body: { items: [] }.to_json,
+                   headers: { "Content-Type" => "application/json" })
+
+      result = merchants.near(latitude: "37.7749", longitude: "-122.4194", country: "US")
+      expect(result["items"]).to eq([])
+    end
+  end
+end