figpay_gateway 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0a09ef25c0277c79ba548c7dea0845e8bcbdc85b98ce4b744f68b38cf3f6a7c
+  data.tar.gz: 8bc4a5747095180ee934641f4a7519a1770bffa72336b38a5a6c6a5896bb21a1
+SHA512:
+  metadata.gz: 586f04f067969ed8ed10712642c0a35a0cae7db3e312f92a2b1fa492ae8ca06e5ebe2e5b08899ef1251cf32954c28cab75e26d8f07305f4ec381e31086990749
+  data.tar.gz: dced5d25b7e481f951bb6e29236b5536eb35822c5ba666e1a817b1065f1c8a765bb70cc997e843e1517d654773031319aaa9db982084b1cd007fc9c83508f9f8

data/.env.sample

@@ -0,0 +1,10 @@
+# Your FigPay/NMI Security Key
+# Get this from: Settings > Security Keys in the merchant control panel
+NMI_SECURITY_KEY=your_security_key_here
+
+# For testing, you can use the demo account security key:
+# NMI_SECURITY_KEY=6457Thfj624V5r7WUwc5v6a68Zsd6YEm
+
+# Optional: Override default API endpoints
+# NMI_TRANSACTION_URL=https://figpay.transactiongateway.com/api/transact.php
+# NMI_QUERY_URL=https://figpay.transactiongateway.com/api/query.php

data/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - "**"
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.0', '3.1', '3.2', '3.3', '3.4']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake test
+        env:
+          NMI_SECURITY_KEY: ${{ secrets.NMI_SECURITY_KEY || '6457Thfj624V5r7WUwc5v6a68Zsd6YEm' }}
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: .ruby-version
+          bundler-cache: true
+
+      - name: Check for syntax errors
+        run: |
+          find . -name '*.rb' -not -path './vendor/*' -exec ruby -c {} \;

data/.gitignore

@@ -0,0 +1,27 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.sublime-project
+*.sublime-workspace
+
+.DS_Store
+.env
+.ruby-version
+.ruby-gemset
+
+# Editor tags files
+tags
+TAGS
+.tags
+.tags1

data/.tool-versions

@@ -0,0 +1,2 @@
+ruby 3.4.5
+nodejs 20.12.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in figpay_gateway.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,42 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?test_(.*)\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb$})      { 'test' }
+
+  # with Minitest::Spec
+  # watch(%r{^spec/(.*)_spec\.rb$})
+  # watch(%r{^lib/(.+)\.rb$})         { |m| "spec/#{m[1]}_spec.rb" }
+  # watch(%r{^spec/spec_helper\.rb$}) { 'spec' }
+
+  # Rails 4
+  # watch(%r{^app/(.+)\.rb$})                               { |m| "test/#{m[1]}_test.rb" }
+  # watch(%r{^app/controllers/application_controller\.rb$}) { 'test/controllers' }
+  # watch(%r{^app/controllers/(.+)_controller\.rb$})        { |m| "test/integration/#{m[1]}_test.rb" }
+  # watch(%r{^app/views/(.+)_mailer/.+})                    { |m| "test/mailers/#{m[1]}_mailer_test.rb" }
+  # watch(%r{^lib/(.+)\.rb$})                               { |m| "test/lib/#{m[1]}_test.rb" }
+  # watch(%r{^test/.+_test\.rb$})
+  # watch(%r{^test/test_helper\.rb$}) { 'test' }
+
+  # Rails < 4
+  # watch(%r{^app/controllers/(.*)\.rb$}) { |m| "test/functional/#{m[1]}_test.rb" }
+  # watch(%r{^app/helpers/(.*)\.rb$})     { |m| "test/helpers/#{m[1]}_test.rb" }
+  # watch(%r{^app/models/(.*)\.rb$})      { |m| "test/unit/#{m[1]}_test.rb" }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Ben Eggett
+
+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,491 @@
+[![Gem Version](https://badge.fury.io/rb/figpay_gateway.svg)](https://badge.fury.io/rb/figpay_gateway)
+
+# FigPay Gateway Ruby Library
+
+The FigPay Gateway Ruby library provides convenient access to the FigPay payment gateway API from applications written in Ruby. FigPay is a white-label payment gateway powered by NMI, and this library is built with portability in mind for other NMI-based gateways.
+
+## Documentation
+
+See the [FigPay API documentation](https://www.figpay.com/) for detailed information about the payment gateway features.
+
+## Requirements
+
+- Ruby 3.0.0 or higher
+
+## Installation
+
+Install the gem and add to your application's Gemfile:
+
+```bash
+gem install figpay_gateway
+```
+
+Or add this line to your Gemfile:
+
+```ruby
+gem 'figpay_gateway'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+The library needs to be configured with your account's security key, which is available in your FigPay merchant control panel under Settings > Security Keys.
+
+### Configuration
+
+Set your security key as an environment variable:
+
+```bash
+export NMI_SECURITY_KEY='your_security_key_here'
+```
+
+Or in a `.env` file:
+
+```
+NMI_SECURITY_KEY=your_security_key_here
+```
+
+For testing, you can use the demo account security key:
+
+```
+NMI_SECURITY_KEY=6457Thfj624V5r7WUwc5v6a68Zsd6YEm
+```
+
+### Quick Start
+
+```ruby
+require 'figpay_gateway'
+
+# Process a sale
+result = FigpayGateway::Transaction.new.sale(
+  ccnumber: '4111111111111111',
+  ccexp: '1225',
+  amount: 10.00,
+  first_name: 'John',
+  last_name: 'Doe',
+  email: 'john@example.com'
+)
+
+if result.success?
+  puts "Transaction approved: #{result.transactionid}"
+else
+  puts "Transaction failed: #{result.response_text} #{result.response_message}"
+end
+```
+
+## API Overview
+
+The FigPay Gateway library is organized around three main API sets:
+
+### Transactions
+
+Process credit card transactions including sales, authorizations, captures, and refunds.
+
+#### Create a Sale
+
+Process a direct sale (authorization and capture combined):
+
+```ruby
+transaction = FigpayGateway::Transaction.new
+
+result = transaction.sale(
+  ccnumber: '4111111111111111',
+  ccexp: '1225',
+  cvv: '999',
+  amount: 25.00,
+  first_name: 'John',
+  last_name: 'Doe',
+  address1: '123 Main St',
+  city: 'Beverly Hills',
+  state: 'CA',
+  zip: '90210',
+  country: 'US',
+  email: 'john@example.com'
+)
+```
+
+#### Authorize and Capture
+
+Authorize a payment for later capture:
+
+```ruby
+# Authorize
+auth = FigpayGateway::Transaction.new.authorize(
+  ccnumber: '4111111111111111',
+  ccexp: '1225',
+  amount: 50.00,
+  first_name: 'John',
+  last_name: 'Doe'
+)
+
+# Capture the authorized amount
+if auth.success?
+  capture = FigpayGateway::Transaction.new.capture(
+    transactionid: auth.transactionid,
+    amount: 50.00
+  )
+end
+```
+
+#### Refund a Transaction
+
+Issue a refund for a previous transaction:
+
+```ruby
+refund = FigpayGateway::Transaction.new.refund(
+  transactionid: '3261844010',
+  amount: 10.00
+)
+```
+
+#### Void a Transaction
+
+Void a transaction before it settles:
+
+```ruby
+void = FigpayGateway::Transaction.new.void(
+  transactionid: '3261830498'
+)
+```
+
+#### Credit (Standalone Credit)
+
+Issue a credit without a previous transaction:
+
+```ruby
+credit = FigpayGateway::Transaction.new.credit(
+  ccnumber: '4111111111111111',
+  ccexp: '1225',
+  amount: 15.00,
+  first_name: 'John',
+  last_name: 'Doe'
+)
+```
+
+#### Validate a Card
+
+Validate card details without charging:
+
+```ruby
+validation = FigpayGateway::Transaction.new.validate(
+  ccnumber: '4111111111111111',
+  ccexp: '1225',
+  first_name: 'John',
+  last_name: 'Doe'
+)
+```
+
+#### Query a Transaction
+
+Retrieve transaction details:
+
+```ruby
+details = FigpayGateway::Transaction.new.find(
+  transactionid: '3261844010'
+)
+```
+
+#### Update Transaction Information
+
+Update transaction details (e.g., order information):
+
+```ruby
+update = FigpayGateway::Transaction.new.update(
+  transactionid: '3261844010',
+  orderid: 'ORDER-12345',
+  order_description: 'Updated order description'
+)
+```
+
+### Customer Vault
+
+Store customer payment information securely for future transactions.
+
+#### Create a Customer
+
+Store customer payment details in the vault:
+
+```ruby
+vault = FigpayGateway::CustomerVault.new
+
+customer = vault.create(
+  ccnumber: '4111111111111111',
+  ccexp: '1225',
+  cvv: '999',
+  first_name: 'Jane',
+  last_name: 'Smith',
+  address1: '456 Oak Ave',
+  city: 'Los Angeles',
+  state: 'CA',
+  zip: '90001',
+  email: 'jane@example.com'
+)
+
+if customer.success?
+  puts "Customer created: #{customer.customer_vault_id}"
+end
+```
+
+#### Update a Customer
+
+Update stored customer information:
+
+```ruby
+update = FigpayGateway::CustomerVault.new.update(
+  customer_vault_id: '481397475',
+  ccnumber: '4111111111111111',
+  ccexp: '0226',
+  first_name: 'Jane',
+  last_name: 'Doe',
+  email: 'jane.doe@example.com'
+)
+```
+
+#### Delete a Customer
+
+Remove a customer from the vault:
+
+```ruby
+delete = FigpayGateway::CustomerVault.new.destroy(
+  customer_vault_id: '481397475'
+)
+```
+
+#### Retrieve Customer Details
+
+Query customer vault information:
+
+```ruby
+customer = FigpayGateway::CustomerVault.new.find(
+  customer_vault_id: '481397475'
+)
+```
+
+#### Charge a Vaulted Customer
+
+Process a transaction using stored payment information:
+
+```ruby
+sale = FigpayGateway::Transaction.new.sale(
+  customer_vault_id: '481397475',
+  amount: 99.99,
+  orderid: 'ORDER-67890'
+)
+```
+
+### Recurring Billing
+
+Set up and manage recurring subscription payments.
+
+#### Create a Billing Plan
+
+Define a reusable billing plan:
+
+```ruby
+recurring = FigpayGateway::Recurring.new
+
+plan = recurring.create_plan(
+  plan_id: 'monthly-premium',
+  plan_name: 'Monthly Premium Plan',
+  plan_amount: 29.99,
+  month_frequency: 1,
+  day_of_month: 1
+)
+```
+
+#### Subscribe Customer to a Plan
+
+Add a vaulted customer to an existing plan:
+
+```ruby
+subscription = FigpayGateway::Recurring.new.add_subscription_to_plan(
+  plan_id: 'monthly-premium',
+  customer_vault_id: '664625840'
+)
+
+if subscription.success?
+  puts "Subscription created: #{subscription.subscription_id}"
+end
+```
+
+#### Create a Custom Subscription
+
+Create a one-off subscription without a predefined plan:
+
+```ruby
+custom_sub = FigpayGateway::Recurring.new.add_custom_subscription(
+  customer_vault_id: '664625840',
+  plan_amount: 49.99,
+  month_frequency: 3,
+  day_of_month: 15,
+  start_date: '20251215'
+)
+```
+
+#### Update a Subscription
+
+Modify subscription details:
+
+```ruby
+update = FigpayGateway::Recurring.new.update_subscription(
+  subscription_id: '3261766445',
+  plan_amount: 39.99
+)
+```
+
+#### Cancel a Subscription
+
+Delete an active subscription:
+
+```ruby
+cancel = FigpayGateway::Recurring.new.delete_subscription(
+  subscription_id: '3261766445'
+)
+```
+
+## Advanced Configuration
+
+### Custom API Endpoints
+
+Override the default FigPay API endpoints if needed:
+
+```bash
+export NMI_TRANSACTION_URL='https://custom.gateway.com/api/transact.php'
+export NMI_QUERY_URL='https://custom.gateway.com/api/query.php'
+```
+
+### Per-Request Configuration
+
+Pass a custom security key for individual requests:
+
+```ruby
+transaction = FigpayGateway::Transaction.new(security_key: 'custom_key_here')
+result = transaction.sale(amount: 10.00, ...)
+```
+
+## Response Handling
+
+All API methods return response objects with helpful methods:
+
+```ruby
+result = FigpayGateway::Transaction.new.sale(...)
+
+# Check transaction status
+if result.success?
+  puts "Success!"
+  puts "Transaction ID: #{result.transactionid}"
+  puts "Auth Code: #{result.authcode}"
+else
+  puts "Failed: #{result.response_text} #{result.response_message}"
+  puts "Response Code: #{result.response_code}"
+end
+
+# Access raw response data
+puts result.response
+```
+
+## Testing
+
+### Test All Methods Against Your Account
+
+The gem includes a comprehensive testing tool that exercises all API methods against a live account. This is useful for:
+
+- Verifying your account configuration
+- Testing all available payment gateway features
+- Ensuring your security key has the necessary permissions
+- Learning how different API methods work
+
+To run the comprehensive test suite:
+
+```bash
+bin/test_all_methods
+```
+
+By default, it uses the demo security key. To test against your own account, set your security key first:
+
+```bash
+export NMI_SECURITY_KEY='your_security_key_here'
+bin/test_all_methods
+```
+
+The test script will:
+
+- Run 18+ different API operations
+- Show detailed results for each test
+- Display a summary with success rate
+- Help identify any configuration issues
+
+**Note**: This will create real test transactions on your account (or the demo account if using the demo key).
+
+### Test Credentials
+
+Use the demo security key for testing:
+
+```ruby
+# In your test environment
+ENV['NMI_SECURITY_KEY'] = '6457Thfj624V5r7WUwc5v6a68Zsd6YEm'
+```
+
+Test card numbers:
+
+- **Visa**: 4111111111111111
+- **Mastercard**: 5555555555554444
+- **Amex**: 378282246310005
+- **Discover**: 6011111111111117
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies:
+
+```bash
+bin/setup
+```
+
+Run the test suite:
+
+```bash
+rake test
+```
+
+Start an interactive console for experimentation:
+
+```bash
+bin/console
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/beneggett/figpay_gateway.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## Support
+
+For issues related to:
+
+- **This library**: Open an issue on [GitHub](https://github.com/beneggett/figpay_gateway/issues)
+- **FigPay Gateway API**: Contact FigPay support
+- **NMI Platform**: Refer to NMI documentation at [nmi.com](https://nmi.com)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## About
+
+Built with portability in mind for NMI-based payment gateways.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+require "dotenv"
+Dotenv.load
+require "bundler/setup"
+require "figpay_gateway"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here