DOCSEARCHbyAlgolia
Submit Docs

Active Merchant Documentation

repository·master·Indexed 26 days ago

https://github.com/activemerchant/active_merchant

A unified Ruby API for integrating dozens of payment gateways into Ruby and Ruby on Rails applications. It provides a standardized interface for common financial operations including authorize, capture, purchase, refund, and void. Supported gateways include Adyen, Authorize.Net, Braintree, PayPal Express Checkout, Stripe, and Worldpay. Compatible with Ruby 2.5+ and Rails 5.0+.

Tokens
4.5K
Snippets
4
Records
47
Agent score
88%

What's inside Active Merchant

  1. Perform gateway operations like purchase, authorize, and capture

    master

    Active Merchant uses subclasses of ActiveMerchant::Billing::Gateway to interface with payment gateways. You can perform three primary operations on a gateway instance:

    1. #authorize: Reserves the required amount on the card holder's credit card.
    2. #capture: Collects the previously authorized funds.
    3. #purchase: Combines authorization and capture into a single operation.

    All three methods return an ActiveMerchant::Billing::Response object. Use response.success? to check if the operation worked and response.message to retrieve error details if it failed.

    gateway = SomeGateway.new

# Amounts are always specified in cents, so $10.00 is 1000 cents
response = gateway.purchase(1000, credit_card)

if response.success?
  puts "Payment complete!"
else
  puts "Payment failed: #{response.message}"
end

  2. View supported payment gateways and feature matrix

    master

    Active Merchant supports a wide variety of payment gateways globally. To check which specific features (like recurring billing, refunds, etc.) are supported by a particular gateway, consult the Gateway Feature Matrix on the ActiveMerchant Wiki.

    Supported gateways include, but are not limited to:

    • Adyen (Multiple regions)
    • Authorize.Net (US, AU, CA)
    • Braintree (Global)
    • PayPal Express Checkout (US, CA, SG, AU, GB, etc.)
    • Stripe (Global)
    • Worldpay (Global)

    For the full list of supported gateways and their regional availability, refer to the documentation provided in the repository.

  5. Use TransArmor tokenization with FirstData e4 v27

    master

    If TransArmor support is activated on your FirstData account, you can tokenize credit cards using the store method.

    When a transaction is successful, the response's authorization attribute contains a semicolon-separated string containing the TransArmor token and card metadata. You can pass this string directly to authorize or purchase methods in place of an ActiveMerchant::Billing::CreditCard instance to perform subsequent transactions without handling raw card data.

  11. Make a purchase using a credit card

    master

    This example demonstrates how to configure a gateway in :test mode, define an amount in cents, create a CreditCard object, and execute a purchase.

    Key details:

    • Set ActiveMerchant::Billing::Base.mode = :test for testing.
    • Amounts must be passed as Integer values in cents (e.g., 1000 for $10.00).
    • Use credit_card.validate to check for card validity; it automatically detects the card type.
    • The response.success? method determines if the transaction was successful.
    require 'active_merchant'

# Use the TrustCommerce test servers
ActiveMerchant::Billing::Base.mode = :test

gateway = ActiveMerchant::Billing::TrustCommerceGateway.new(
            :login => 'TestMerchant',
            :password => 'password')

# ActiveMerchant accepts all amounts as Integer values in cents
amount = 1000  # $10.00

# The card verification value is also known as CVV2, CVC2, or CID
credit_card = ActiveMerchant::Billing::CreditCard.new(
                :first_name         => 'Bob',
                :last_name          => 'Bobsen',
                :number             => '4242424242424242',
                :month              => '8',
                :year               => Time.now.year+1,
                :verification_value => '000')

# Validating the card automatically detects the card type
if credit_card.validate.empty?
  # Capture $10 from the credit card
  response = gateway.purchase(amount, credit_card)

  if response.success?
    puts "Successfully charged $#{sprintf("%.2f", amount / 100)} to the credit card #{credit_card.display_number}"
  else
    raise StandardError, response.message
  end
end