pushpay-ruby 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3050bdf6e88d960e882abd161991931364db856d95928ef699febbf990dcc4e
+  data.tar.gz: 5a5b91dd42cbbf22f4b9b53b22088d519559b6cbf2c43f764061cb4930c011f8
+SHA512:
+  metadata.gz: ee443d65225547f53bb4e2d44add1d7ecf83a6b11d06d1a2bb516cf638297bf67d496f8d3f73c3d6c52a003fe7026ad6c9a0746f9f0cca41bd3001fdbebd07a7
+  data.tar.gz: 59a571448c813a1398ba7de36146b0510e7be5f88ea0936c120591de5bb2b4cb7a766cd85070aa2bf90129de8db9fcef64250b7894e1fc922e8b40f0816a366c

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-24
+
+### Changed
+- **Breaking:** Rewritten to match the actual PushPay API
+- Authentication now uses the correct PushPay OAuth 2.0 endpoint (`auth.pushpay.com`) with Basic auth
+- All endpoints use `/v1/` prefix and are scoped by merchant/organization key
+- Configuration uses `client_id`/`client_secret` instead of `application_key`/`application_secret`
+- Responses use HAL+JSON format (`application/hal+json`)
+- Token expiration tracking with automatic re-authentication
+
+### Added
+- `sandbox!` configuration method for sandbox environment
+- `scopes` configuration for OAuth scope requests
+- `RecurringPayment` resource (list, find, linked payments)
+- `AnticipatedPayment` resource (create, list)
+- `Organization` resource (find, search, in_scope, campuses, merchant_listings)
+- `Fund` resource (CRUD + status updates)
+- `Settlement` resource (list, find, payments)
+- `Batch` resource (list, find, payments)
+- `Webhook` resource (CRUD)
+- `NotFoundError` for 404 responses
+- `RateLimitError` now includes `retry_after` value
+- `Base` resource class with merchant/organization path helpers
+- All resources default to `PushPay.client` when no client is passed
+- `PATCH` support on the HTTP client
+
+### Removed
+- `Donation` resource (not a real PushPay API resource)
+- `PaymentPlan` resource (replaced by `RecurringPayment`)
+- `Transaction` resource (not a standalone PushPay API resource)
+- `jwt` dependency (not needed)
+- Hardcoded credentials from client
+- Client-side validation on resources (let the API validate)
+
+## [0.1.1] - 2024-12-01
+
+### Added
+- Initial scaffolding release
+
+## [0.1.0] - 2024-11-15
+
+### Added
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Eduardo Souza
+
+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,244 @@
+# PushPay Ruby
+
+Ruby gem for integrating with the [PushPay](https://pushpay.com) payment processing API. Supports payments, recurring payments, anticipated payments, funds, merchants, organizations, settlements, batches, and webhooks.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'pushpay'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install pushpay
+```
+
+## Configuration
+
+```ruby
+PushPay.configure do |config|
+  config.client_id        = ENV['PUSHPAY_CLIENT_ID']
+  config.client_secret    = ENV['PUSHPAY_CLIENT_SECRET']
+  config.merchant_key     = ENV['PUSHPAY_MERCHANT_KEY']
+  config.organization_key = ENV['PUSHPAY_ORGANIZATION_KEY']
+
+  # Optional
+  config.scopes  = %w[read merchant:view_payments]
+  config.timeout = 30 # seconds, default
+
+  # Use sandbox environment
+  # config.sandbox!
+end
+```
+
+## Usage
+
+All resources can be initialized without arguments (uses `PushPay.client` by default) or with an explicit client.
+
+### Payments
+
+Payments are read-only in the PushPay API.
+
+```ruby
+payments = PushPay::Payment.new
+
+# Get a single payment
+payments.find('payment_token')
+
+# List merchant payments with filters
+payments.list(status: 'Success', pageSize: 10, from: '2024-01-01')
+
+# List payments across an organization
+payments.list_for_organization
+```
+
+### Recurring Payments
+
+```ruby
+recurring = PushPay::RecurringPayment.new
+
+# Get a recurring payment
+recurring.find('recurring_token')
+
+# List recurring payments
+recurring.list
+
+# Get payments linked to a recurring schedule
+recurring.payments('recurring_token')
+
+# List across an organization
+recurring.list_for_organization
+```
+
+### Anticipated Payments
+
+Create payment links that can be sent to payers.
+
+```ruby
+anticipated = PushPay::AnticipatedPayment.new
+
+# Create an anticipated payment
+anticipated.create({ amount: '50.00' })
+
+# List anticipated payments
+anticipated.list
+```
+
+### Merchants
+
+```ruby
+merchants = PushPay::Merchant.new
+
+# Get a specific merchant
+merchants.find('merchant_key')
+
+# Search merchants
+merchants.search(name: 'Church')
+
+# List accessible merchants
+merchants.in_scope
+
+# Search nearby
+merchants.near(latitude: '37.7749', longitude: '-122.4194', country: 'US')
+```
+
+### Organizations
+
+```ruby
+orgs = PushPay::Organization.new
+
+# Get an organization
+orgs.find('org_key')
+
+# List accessible organizations
+orgs.in_scope
+
+# List campuses
+orgs.campuses
+
+# List merchant listings
+orgs.merchant_listings
+```
+
+### Funds
+
+```ruby
+funds = PushPay::Fund.new
+
+# List funds for a merchant
+funds.list
+
+# List funds for an organization
+funds.list_for_organization
+
+# Get a specific fund
+funds.find('fund_key')
+
+# Create a fund
+funds.create({ name: 'Missions', taxDeductible: true })
+
+# Update a fund
+funds.update('fund_key', { name: 'Updated Name' })
+
+# Delete a fund
+funds.delete('fund_key')
+```
+
+### Settlements
+
+```ruby
+settlements = PushPay::Settlement.new
+
+# List settlements
+settlements.list
+
+# Get a specific settlement
+settlements.find('settlement_key')
+
+# Get payments within a settlement
+settlements.payments('settlement_key')
+```
+
+### Batches
+
+```ruby
+batches = PushPay::Batch.new
+
+# List batches
+batches.list
+
+# Get a specific batch
+batches.find('batch_key')
+
+# Get payments within a batch
+batches.payments('batch_key')
+```
+
+### Webhooks
+
+```ruby
+webhooks = PushPay::Webhook.new
+
+# List webhooks
+webhooks.list
+
+# Create a webhook
+webhooks.create({ target: 'https://example.com/webhook', eventTypes: ['payment_created'] })
+
+# Update a webhook
+webhooks.update('webhook_token', { target: 'https://example.com/new' })
+
+# Delete a webhook
+webhooks.delete('webhook_token')
+```
+
+### Using a Custom Merchant/Organization Key
+
+All merchant/org-scoped methods accept an optional key override:
+
+```ruby
+payments.list(merchant_key: 'other_merchant')
+funds.list_for_organization(organization_key: 'other_org')
+```
+
+## Error Handling
+
+```ruby
+begin
+  payments.list
+rescue PushPay::ConfigurationError => e
+  # Missing API credentials
+rescue PushPay::AuthenticationError => e
+  # OAuth authentication failed
+rescue PushPay::ValidationError => e
+  puts e.errors # Detailed validation failures
+rescue PushPay::NotFoundError => e
+  # 404 - Resource not found
+rescue PushPay::RateLimitError => e
+  puts e.retry_after # Seconds to wait
+rescue PushPay::APIError => e
+  puts e.status_code
+  puts e.response_body
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/pushpay/anticipated_payment.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PushPay
+  class AnticipatedPayment < Base
+    # Create a new anticipated payment
+    def create(params, merchant_key: nil)
+      client.post("#{merchant_path(merchant_key)}/anticipatedpayments", params)
+    end
+
+    # List anticipated payments for a merchant
+    def list(merchant_key: nil, **params)
+      client.get("#{merchant_path(merchant_key)}/anticipatedpayments", params)
+    end
+  end
+end

data/lib/pushpay/base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Base
+    attr_reader :client
+
+    def initialize(client = nil)
+      @client = client || PushPay.client
+    end
+
+    private
+
+    def merchant_path(merchant_key = nil)
+      key = merchant_key || client.configuration.merchant_key
+      raise ConfigurationError, ["merchant_key"] unless key
+      "/v1/merchant/#{key}"
+    end
+
+    def organization_path(organization_key = nil)
+      key = organization_key || client.configuration.organization_key
+      raise ConfigurationError, ["organization_key"] unless key
+      "/v1/organization/#{key}"
+    end
+  end
+end

data/lib/pushpay/batch.rb

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

data/lib/pushpay/client.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module PushPay
+  class Client
+    include HTTParty
+
+    attr_reader :configuration, :access_token, :token_expires_at
+
+    def initialize(configuration)
+      @configuration = configuration
+      validate_configuration!
+      @access_token = nil
+      @token_expires_at = nil
+    end
+
+    def authenticate!
+      credentials = Base64.strict_encode64("#{configuration.client_id}:#{configuration.client_secret}")
+
+      scopes = configuration.scopes.empty? ? ["read"] : configuration.scopes
+      body = { grant_type: 'client_credentials', scope: scopes.join(' ') }
+
+      response = self.class.post(
+        configuration.auth_url,
+        body: body,
+        headers: {
+          'Authorization' => "Basic #{credentials}",
+          'Content-Type' => 'application/x-www-form-urlencoded'
+        },
+        timeout: configuration.timeout
+      )
+
+      unless response.success?
+        raise AuthenticationError, "Failed to authenticate: #{response.code} - #{response.body}"
+      end
+
+      @access_token = response['access_token']
+      @token_expires_at = Time.now + (response['expires_in'] || 3600)
+      @access_token
+    end
+
+    def get(path, params = {})
+      request(:get, path, query: params)
+    end
+
+    def post(path, data = {})
+      request(:post, path, body: data.to_json)
+    end
+
+    def put(path, data = {})
+      request(:put, path, body: data.to_json)
+    end
+
+    def patch(path, data = {})
+      request(:patch, path, body: data.to_json)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def validate_configuration!
+      missing = configuration.missing_credentials
+      raise ConfigurationError, missing unless missing.empty?
+    end
+
+    def ensure_authenticated!
+      authenticate! if @access_token.nil? || token_expired?
+    end
+
+    def token_expired?
+      @token_expires_at && Time.now >= @token_expires_at
+    end
+
+    def request(method, path, options = {})
+      ensure_authenticated!
+
+      url = "#{configuration.base_url}#{path}"
+      request_options = {
+        headers: auth_headers,
+        timeout: configuration.timeout
+      }
+
+      if options[:query]
+        request_options[:query] = options[:query]
+      end
+
+      if options[:body]
+        request_options[:body] = options[:body]
+        request_options[:headers] = request_options[:headers].merge('Content-Type' => 'application/json')
+      end
+
+      response = self.class.send(method, url, request_options)
+      handle_response(response)
+    end
+
+    def auth_headers
+      {
+        'Authorization' => "Bearer #{@access_token}",
+        'Accept' => 'application/hal+json'
+      }
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200, 201, 202, 204
+        response.parsed_response
+      when 401
+        @access_token = nil
+        @token_expires_at = nil
+        raise AuthenticationError, "Authentication failed: #{response.body}"
+      when 404
+        raise NotFoundError.new("Resource not found", response.code, response.body)
+      when 429
+        retry_after = response.headers['retry-after']
+        raise RateLimitError.new("Rate limit exceeded", response.code, response.body, retry_after)
+      when 400, 422
+        parsed = response.parsed_response || {}
+        errors = parsed['validationFailures'] || {}
+        raise ValidationError.new(
+          parsed['message'] || 'Validation failed',
+          response.code,
+          response.body,
+          errors
+        )
+      when 500..599
+        raise APIError.new("Server error", response.code, response.body)
+      else
+        raise APIError.new("Unexpected response", response.code, response.body)
+      end
+    end
+  end
+end

data/lib/pushpay/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Configuration
+    attr_accessor :client_id, :client_secret, :merchant_key, :organization_key,
+                  :base_url, :auth_url, :timeout, :scopes
+
+    def initialize
+      @base_url = "https://api.pushpay.io"
+      @auth_url = "https://auth.pushpay.com/pushpay/oauth/token"
+      @timeout = 30
+      @scopes = ["read"]
+    end
+
+    def sandbox!
+      @base_url = "https://sandbox-api.pushpay.io"
+      @auth_url = "https://auth.pushpay.com/pushpay-sandbox/oauth/token"
+      self
+    end
+
+    def valid?
+      !client_id.nil? && !client_id.empty? &&
+        !client_secret.nil? && !client_secret.empty?
+    end
+
+    def missing_credentials
+      missing = []
+      missing << "client_id" if client_id.nil? || client_id.to_s.empty?
+      missing << "client_secret" if client_secret.nil? || client_secret.to_s.empty?
+      missing
+    end
+  end
+end

data/lib/pushpay/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Error < StandardError; end
+
+  class ConfigurationError < Error
+    def initialize(missing_credentials)
+      super("Missing required credentials: #{missing_credentials.join(', ')}")
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message = "Authentication failed")
+      super(message)
+    end
+  end
+
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code = nil, response_body = nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  class ValidationError < APIError
+    attr_reader :errors
+
+    def initialize(message, status_code = nil, response_body = nil, errors = {})
+      super(message, status_code, response_body)
+      @errors = errors
+    end
+  end
+
+  class NotFoundError < APIError
+    def initialize(message = "Resource not found", status_code = 404, response_body = nil)
+      super(message, status_code, response_body)
+    end
+  end
+
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", status_code = 429, response_body = nil, retry_after = nil)
+      super(message, status_code, response_body)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/pushpay/fund.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Fund < Base
+    # Get a specific fund
+    def find(fund_key, organization_key: nil)
+      client.get("#{organization_path(organization_key)}/fund/#{fund_key}")
+    end
+
+    # List funds for a merchant
+    def list(merchant_key: nil, **params)
+      client.get("#{merchant_path(merchant_key)}/funds", params)
+    end
+
+    # List funds for an organization
+    def list_for_organization(organization_key: nil, **params)
+      client.get("#{organization_path(organization_key)}/funds", params)
+    end
+
+    # Create a fund
+    def create(params, organization_key: nil)
+      client.post("#{organization_path(organization_key)}/funds", params)
+    end
+
+    # Update a fund
+    def update(fund_key, params, organization_key: nil)
+      client.put("#{organization_path(organization_key)}/fund/#{fund_key}", params)
+    end
+
+    # Change fund status (open/close)
+    def update_status(fund_key, params, organization_key: nil)
+      client.patch("#{organization_path(organization_key)}/fund/#{fund_key}", params)
+    end
+
+    # Delete a fund
+    def delete(fund_key, organization_key: nil)
+      client.delete("#{organization_path(organization_key)}/fund/#{fund_key}")
+    end
+  end
+end

data/lib/pushpay/merchant.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PushPay
+  class Merchant < Base
+    # Get a specific merchant
+    def find(merchant_key)
+      client.get("/v1/merchant/#{merchant_key}")
+    end
+
+    # Search merchants by name or handle
+    def search(**params)
+      client.get("/v1/merchants", params)
+    end
+
+    # List merchants accessible to the current application
+    def in_scope(**params)
+      client.get("/v1/merchants/in-scope", params)
+    end
+
+    # Search for merchants near a location
+    def near(latitude:, longitude:, country: nil, **params)
+      query = { latitude: latitude, longitude: longitude }
+      query[:country] = country if country
+      query.merge!(params)
+      client.get("/v1/merchants/near", query)
+    end
+  end
+end