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.

See the FigPay API documentation for detailed information about the payment gateway features.

• Ruby 3.0.0 or higher

Install the gem and add to your application's Gemfile:

gem install figpay_gateway

Or add this line to your Gemfile:

gem 'figpay_gateway'

And then execute:

bundle install

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.

You can configure the library in two ways:

Set your security key as an environment variable:

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

Create an initializer file (e.g., config/initializers/figpay_gateway.rb):

FigpayGateway.configure do |config|
  config.security_key = Rails.application.credentials.dig(:nmi, :security_key)
  # Optional: customize gateway URLs (defaults shown)
  # config.transaction_url = 'https://figpay.transactiongateway.com/api/transact.php'
  # config.query_url = 'https://figpay.transactiongateway.com/api/query.php'
  # config.test_mode = 'enabled' # Enable test mode
end

Note: You can use either FigpayGateway.configure or NMIGateway.configure - both work identically. Configuration values set via the initializer take precedence over environment variables.

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

The FigPay Gateway library is organized around three main API sets:

Process credit card transactions including sales, authorizations, captures, and refunds.

The payment gateway supports credit card tokenization via Collect.js. The benefit of this approach is that sensitive PCI information will be submitted directly to payment processor servers, they will return a token that you would send back to your servers, and reduce the PCI SAQ compliance requirements from SAQ-C or SAQ-D to SAQ-A. This greatly simplifies compliance, as no credit information would ever touch your logs or servers.

Test Token example: 00000000-000000-000000-000000000000 This is tied to a test card: Card: 4111111111111111, Expiration: October 2025, CVV: 999

Usage, in all examples, rather than passing in ccnumber and ccexp, these can be updated to use the token obtained via Collect.js and passed in as a payment_token param instead.

There is a Test Public Key that can be used with Collect.js: 48r3R6-M39Jx5-467srN-VWVbD3

Process a direct sale (authorization and capture combined):

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 a payment for later capture:

# 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

Issue a refund for a previous transaction:

refund = FigpayGateway::Transaction.new.refund(
  transactionid: '3261844010',
  amount: 10.00
)

Void a transaction before it settles:

void = FigpayGateway::Transaction.new.void(
  transactionid: '3261830498'
)

Issue a credit without a previous transaction:

credit = FigpayGateway::Transaction.new.credit(
  ccnumber: '4111111111111111',
  ccexp: '1225',
  amount: 15.00,
  first_name: 'John',
  last_name: 'Doe'
)

Validate card details without charging:

validation = FigpayGateway::Transaction.new.validate(
  ccnumber: '4111111111111111',
  ccexp: '1225',
  first_name: 'John',
  last_name: 'Doe'
)

Retrieve transaction details:

details = FigpayGateway::Transaction.new.find(
  transaction_id: '3261844010'
)

Update transaction details (e.g., order information):

update = FigpayGateway::Transaction.new.update(
  transactionid: '3261844010',
  orderid: 'ORDER-12345',
  order_description: 'Updated order description'
)

Store customer payment information securely for future transactions.

Store customer payment details in the vault:

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 stored customer information:

update = FigpayGateway::CustomerVault.new.update(
  customer_vault_id: '481397475',
  ccnumber: '4111111111111111',
  ccexp: '0226',
  first_name: 'Jane',
  last_name: 'Doe',
  email: 'jane.doe@example.com'
)

Remove a customer from the vault:

delete = FigpayGateway::CustomerVault.new.destroy(
  customer_vault_id: '481397475'
)

Query customer vault information:

customer = FigpayGateway::CustomerVault.new.find(
  customer_vault_id: '481397475'
)

Process a transaction using stored payment information:

sale = FigpayGateway::Transaction.new.sale(
  customer_vault_id: '481397475',
  amount: 99.99,
  orderid: 'ORDER-67890'
)

Set up and manage recurring subscription payments.

Define a reusable billing plan:

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
)

Retrieve all recurring billing plans:

plans = FigpayGateway::Recurring.new.list_plans

if plans.success?
  puts "Plans retrieved successfully"
end

Note: The Query API may not be available on all accounts. Contact FigPay support if you encounter issues.

Add a vaulted customer to an existing plan:

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 one-off subscription without a predefined plan:

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'
)

Modify subscription details:

update = FigpayGateway::Recurring.new.update_subscription(
  subscription_id: '3261766445',
  plan_amount: 39.99
)

Delete an active subscription:

cancel = FigpayGateway::Recurring.new.delete_subscription(
  subscription_id: '3261766445'
)

Override the default FigPay API endpoints if needed:

export NMI_TRANSACTION_URL='https://custom.gateway.com/api/transact.php'
export NMI_QUERY_URL='https://custom.gateway.com/api/query.php'

Pass a custom security key for individual requests:

transaction = FigpayGateway::Transaction.new(security_key: 'custom_key_here')
result = transaction.sale(amount: 10.00, ...)

All API methods return response objects with helpful methods:

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

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:

bin/test_all_methods

By default, it uses the demo security key. To test against your own account, set your security key first:

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).

Use the demo security key for testing:

# In your test environment
ENV['NMI_SECURITY_KEY'] = '6457Thfj624V5r7WUwc5v6a68Zsd6YEm'

Test card numbers:

• Visa: 4111111111111111
• Mastercard: 5555555555554444
• Amex: 378282246310005
• Discover: 6011111111111117

After checking out the repo, run bin/setup to install dependencies:

bin/setup

Run the test suite:

rake test

Start an interactive console for experimentation:

bin/console

To install this gem onto your local machine:

bundle exec rake install

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

For issues related to:

• This library: Open an issue on GitHub
• FigPay Gateway API: Contact FigPay support
• NMI Platform: Refer to NMI documentation at nmi.com

The gem is available as open source under the terms of the MIT License.

Built with portability in mind for NMI-based payment gateways.