If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/activemerchant/active_merchant shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6mo ago
• 19 active contributors
• Distributed ownership (top contributor 15% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live activemerchant/active_merchant repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/activemerchant/active_merchant.

What it runs against: a local clone of activemerchant/active_merchant — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in activemerchant/active_merchant | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 217 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of activemerchant/active_merchant. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/activemerchant/active_merchant.git
#   cd active_merchant
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of activemerchant/active_merchant and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "activemerchant/active_merchant(\\.git)?\\b" \\
  && ok "origin remote is activemerchant/active_merchant" \\
  || miss "origin remote is not activemerchant/active_merchant (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/active_merchant/billing/gateway.rb" \\
  && ok "lib/active_merchant/billing/gateway.rb" \\
  || miss "missing critical file: lib/active_merchant/billing/gateway.rb"
test -f "lib/active_merchant/billing/credit_card.rb" \\
  && ok "lib/active_merchant/billing/credit_card.rb" \\
  || miss "missing critical file: lib/active_merchant/billing/credit_card.rb"
test -f "lib/active_merchant/billing/gateways.rb" \\
  && ok "lib/active_merchant/billing/gateways.rb" \\
  || miss "missing critical file: lib/active_merchant/billing/gateways.rb"
test -f "lib/active_merchant.rb" \\
  && ok "lib/active_merchant.rb" \\
  || miss "missing critical file: lib/active_merchant.rb"
test -f "lib/active_merchant/billing.rb" \\
  && ok "lib/active_merchant/billing.rb" \\
  || miss "missing critical file: lib/active_merchant/billing.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 217 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~187d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/activemerchant/active_merchant"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Active Merchant is a Ruby payment processing abstraction library that provides a unified API to interact with 100+ different payment gateways (Stripe, Adyen, Authorize.net, etc.). Instead of learning each gateway's unique API, developers write once against Active Merchant's consistent interface and can swap gateways by changing configuration. It handles credit card validation, authorization, capture, refunds, and recurring billing across vastly different provider implementations. Monolithic gem structure: lib/active_merchant/billing/ is the core, containing base.rb (root class), gateway.rb (payment gateway abstraction), credit_card.rb (card handling), and gateways/ subdirectory with 100+ individual gateway implementations (adyen.rb, authorize_net.rb, stripe.rb, etc.). Each gateway inherits from Gateway and implements authorize, capture, purchase, and refund methods. Support utilities include avs_result.rb, cvv_result.rb, and apple_pay_payment_token.rb for response parsing.

Ruby on Rails developers and standalone Ruby application developers who need to process payments and integrate with multiple payment processors without reimplementing gateway logic for each provider. Also: fintech companies using Ruby that need to support multiple payment methods and gateways simultaneously.

Highly mature and production-ready. The library has been in production use since June 2006 at Shopify and is actively maintained by Shopify and Spreedly teams. The codebase shows ~11.7M lines of Ruby, comprehensive CI/CD via GitHub Actions (.github/workflows/ruby-ci.yml), and supports Rails 4.2 through master with gemfiles for each version. Actively developed with ongoing gateway integrations and updates.

Low risk for core functionality but moderate risk for specific gateways: individual gateway implementations vary in maturity and testing coverage (some gateways may have limited contributor attention). The monolithic structure means a breaking change to the base Gateway class affects all downstream integrations. Dependency on external payment providers means stability depends partially on third-party API reliability and deprecations.

Active development of new gateway integrations (airwallex.rb, alelo.rb, allied_wallet.rb, axcessms.rb visible in recent files) and compatibility across Rails versions (gemfiles for Rails 4.2–master). CI pipeline runs against multiple Ruby/Rails combinations via ruby-ci.yml. The project appears to be in steady maintenance mode with incremental gateway additions rather than major architectural changes.

git clone git://github.com/activemerchant/active_merchant.git && cd active_merchant && bundle install (Gemfile present in root). Verify setup with: bundle exec rake test to run the test suite. No server startup required; this is a library for integration into your own app.

Daily commands: Not a runnable server; it's a library. To use it in your app: require 'active_merchant', instantiate a gateway (e.g., ActiveMerchant::Billing::StripeGateway.new(:login => 'key')), create a CreditCard object, call gateway.purchase(amount, credit_card). See examples/example.rb in README snippet or GettingStarted.md for full walkthrough.

• lib/active_merchant/billing/gateway.rb — Core Gateway base class that all payment gateways inherit from; defines the unified API contract and common methods every contributor must understand.
• lib/active_merchant/billing/credit_card.rb — Credit card abstraction layer handling validation and formatting; essential for understanding payment instrument modeling across all gateways.
• lib/active_merchant/billing/gateways.rb — Registry and loader for all gateway implementations; critical entry point for understanding how gateways are discovered and instantiated.
• lib/active_merchant.rb — Main library entry point and namespace definition; establishes the public API surface and module structure.
• lib/active_merchant/billing.rb — Billing module configuration and core class imports; bridges the main library to billing functionality.
• activemerchant.gemspec — Gem specification defining dependencies, versioning, and public API; required reading for understanding project constraints and requirements.
• GettingStarted.md — Primary documentation for library usage patterns and conventions; establishes the mental model and intended usage patterns.

Add a New Payment Gateway

1. Create gateway class inheriting from Gateway base class in lib/active_merchant/billing/gateways/ (lib/active_merchant/billing/gateways/my_gateway.rb)
2. Implement required methods: purchase, authorize, capture, refund with Response objects (lib/active_merchant/billing/gateways/my_gateway.rb)
3. Register gateway in the gateways registry by requiring it (lib/active_merchant/billing/gateways.rb)
4. Create test file matching gateway structure with unit tests (test/unit/gateways/my_gateway_test.rb)
5. Optionally add remote integration tests with real API calls (test/remote/gateways/my_gateway_test.rb)

Add a New Payment Instrument Type

1. Create new payment instrument class inheriting from base payment abstraction (lib/active_merchant/billing/my_payment_instrument.rb)
2. Implement validation and formatting methods following CreditCard pattern (lib/active_merchant/billing/my_payment_instrument.rb)
3. Update Gateway to accept new instrument type in transaction methods (lib/active_merchant/billing/gateway.rb)
4. Create unit tests for validation and edge cases (test/unit/billing/my_payment_instrument_test.rb)

Add a New Response Normalization Layer

1. Create result class for gateway-specific response normalization (lib/active_merchant/billing/my_result.rb)
2. Implement parsing logic to map gateway-specific codes to normalized values (lib/active_merchant/billing/my_result.rb)
3. Update gateway to populate result object in response handling (lib/active_merchant/billing/gateways/my_gateway.rb)
4. Add unit tests validating normalization of edge cases (test/unit/billing/my_result_test.rb)

Add Gateway-Specific Submodule (e.g., ARB, CIM)

1. Create submodule directory for related gateway variants (lib/active_merchant/billing/gateways/my_gateway/)
2. Create core module with shared functionality (lib/active_merchant/billing/gateways/my_gateway/my_gateway_core.rb)
3. Create variant gateway classes including the core module (lib/active_merchant/billing/gateways/my_gateway_variant.rb)
4. Register all variant gateways in main gateways registry (lib/active_merchant/billing/gateways.rb)

• Ruby language — Extracted from Shopify's Rails stack; provides elegant metaprogramming for gateway abstraction and natural DSL-like payment interfaces.
• Gateway inheritance hierarchy — Enables consistent interface across 100+ payment providers with wildly different APIs through polymorphism and template method pattern.
• Response normalization objects (AVSResult, CVVResult) — Shields application code from gateway-specific error codes and response formats by mapping to standardized result codes.
• Credit card validation library integration — Centralizes payment instrument validation (Luhn algorithm, type detection, expiry) to prevent invalid requests reaching gateways.
• HTTP client abstraction — Allows flexible HTTP backend (Net::HTTP, typhoeus, etc.) without coupling gateway implementations to specific transport layer.

• Unified Response object across all gateways vs gateway-specific response subclasses

  • Why: Simplifies client code and enables gateway swapping without application-level changes
  • Consequence: Gateway-specific fields must be stored in opaque message/raw_response fields; some data loss possible

• Synchronous request/response model vs async event-driven

  • Why: Matches Rails request lifecycle and simplifies usage for typical ecommerce transactions
  • Consequence: Long-running operations (settlements, reporting) may block Rails threads; webhooks must be handled separately

• Plain Ruby classes vs DSL/configuration approach

  • Why: Familiar to Rails developers; allows flexible method overrides and inheritance patterns
  • Consequence: More boilerplate per gateway; less constraint on implementation consistency

• Support for both deprecated and modern gateway APIs in same codebase

  • Why: Backward compatibility with existing integrations prevents forced upgrade cycles
  • Consequence: Code contains compatibility shims and conditional logic; total codebase size larger

• Does not handle recurring billing/subscription logic (gateway-specific implementations exist but no unified interface)
• Does not provide PCI compliance or tokenization infrastructure (relies on gateway tokens)
• Does not manage payment instrument storage or PCI-scope reduction directly (tokenization delegated to gateways)
• Does not implement real-time fraud detection (passes through gateway-provided fraud scores)
• Does not provide transaction reconciliation or settlement reporting (focus on transaction submission only)

1. Test environment vs. production: ActiveMerchant::Billing::Base.mode = :test must be set in code or fixtures to avoid hitting real payment processors during testing; this is not automatic and can cause accidental charges if forgotten. 2) Amount is always in cents: The library exclusively uses integer cents (1000 = $10.00), not dollars; mixing up this convention causes incorrect charges. 3) Gateway-specific credentials: Each gateway in gateways/ expects different :login, :password, :api_key credentials; check individual gateway file docstrings for required credentials or tests will fail silently. 4) CVV/verification_value lifecycle: Most gateways discard CVV immediately after authorization (per PCI-DSS); you cannot re-use or store it between transactions. 5) No built-in retries or idempotency: The library does not automatically retry failed requests or enforce idempotent keys; implementers must handle themselves.

• Payment Gateway Abstraction via Adapter Pattern — Active Merchant's entire design is built on this pattern—the Gateway base class is the abstraction, each provider's gateway is a concrete adapter. Understanding this is essential to adding new gateways or modifying existing ones without touching core code.
• Authorization vs. Capture (Two-Step Payment Processing) — Most payment gateways split payment into authorize (reserve funds, return approval code) and capture (actually charge the card). Active Merchant models both as separate methods; misunderstanding this causes funds to be reserved but never charged, or charges without prior authorization.
• PCI Compliance & Sensitive Data Handling — Active Merchant is designed to avoid storing credit card data locally; it passes cards directly to gateways and never logs CVV. Understanding PCI-DSS scope is critical when extending Active Merchant to ensure you don't accidentally store restricted data.
• AVS (Address Verification System) and CVV Results — Gateways return opaque codes (e.g., 'M' for AVS match, 'I' for no response) that Active Merchant normalizes into AvsResult and CvvResult objects; understanding these codes prevents over-rejecting valid transactions.
• Recurring Billing / Subscription Tokens — Some gateways (Authorize.net CIM, Braintree) support storing customer payment profiles server-side to enable subscriptions without re-entering card data; Active Merchant abstracts this via store/update/unstore methods, but implementation varies per gateway.
• Idempotency Keys & Duplicate Prevention — Network failures can cause duplicate charges if a transaction request succeeds server-side but fails to return the response to the client; many gateways support idempotency keys to prevent this, but Active Merchant does not enforce them by default—implementers must handle.
• XML & JSON Response Parsing — Different gateways return responses in XML (Authorize.net, Adyen) or JSON (modern APIs) with different structures; Active Merchant's response classes parse these into a unified format, requiring knowledge of REXML/Nokogiri for XML gateways.

• spreedly/spreedly-gem — Spreedly is a co-maintainer of Active Merchant and provides an alternative payment orchestration API; this gem wraps Spreedly's hosted gateway service, complementary to Active Merchant.
• stripe/stripe-ruby — Direct competitor for payment processing integration; Active Merchant includes Stripe as one gateway among many, while stripe-ruby is Stripe's first-party client with richer Stripe-specific features.
• braintree/braintree_ruby — Braintree's official Ruby SDK, similar tier to stripe-ruby; Active Merchant includes Braintree as a gateway option, making them alternatives for Braintree-specific projects.
• paypal/PayPal-Ruby-SDK — PayPal's official Ruby SDK; Active Merchant integrates PayPal Express and Adaptive Payments, but PayPal's SDK may offer deeper PayPal-specific features.
• activemerchant/active_merchant_iveri — Community fork adding specialized African payment gateway (Iveri) support, demonstrating the extensibility pattern for adding regional/niche payment providers to Active Merchant.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive remote integration tests for Braintree gateway variants

The repo has multiple Braintree gateway implementations (braintree.rb, braintree_blue.rb, braintree_orange.rb) with a shared braintree_common.rb module, but no dedicated remote test suite. Given Braintree's complexity and the existence of gateway generator templates (generators/gateway/templates/remote_gateway_test.rb), adding remote tests would catch integration issues early and serve as a template for other gateway maintainers.

• [ ] Create test/remote/gateways/remote_braintree_test.rb following the pattern in generators/gateway/templates/remote_gateway_test.rb
• [ ] Create test/remote/gateways/remote_braintree_blue_test.rb for the Blue variant
• [ ] Create test/remote/gateways/remote_braintree_orange_test.rb for the Orange variant
• [ ] Implement purchase, authorize, capture, void, and refund test cases for each
• [ ] Add Braintree sandbox credentials handling to .github/workflows/ruby-ci.yml or as secure env vars

Refactor and consolidate duplicate gateway code in lib/active_merchant/billing/gateways/ directory

The gateways directory has 50+ gateway files with likely duplicated request/response handling patterns. For example, beanstream.rb has a beanstream/ subdirectory with beanstream_core.rb, and braintree.rb has a similar pattern. Identifying and extracting common concerns (XML/JSON parsing, error handling, AVS/CVV result mapping) into shared modules would reduce maintenance burden and improve consistency.

• [ ] Analyze lib/active_merchant/billing/base.rb and lib/active_merchant/billing/gateway.rb for shared interface patterns
• [ ] Create lib/active_merchant/billing/gateways/gateway_helpers/ directory with modules for common patterns
• [ ] Extract XML parsing helpers (seen in multiple gateways) into lib/active_merchant/billing/gateways/gateway_helpers/xml_helper.rb
• [ ] Extract JSON request building into lib/active_merchant/billing/gateways/gateway_helpers/json_helper.rb
• [ ] Refactor at least 3 similar gateways (e.g., barclaycard_smartpay.rb, barclays_epdq_extra_plus.rb) to use the new helpers
• [ ] Add unit tests for each new helper module

Add missing unit tests for credit card validation modules

The lib/active_merchant/billing/ directory contains credit_card_methods.rb, credit_card_formatting.rb, and credit_card.rb without corresponding comprehensive test files in test/unit/. Credit card validation is security-critical and the existing tests likely don't cover edge cases for different card types (Amex, Discover, etc.) and formatting rules.

• [ ] Create test/unit/billing/credit_card_methods_test.rb with tests for detect_card_brand, valid_card_brand?, and other detection logic
• [ ] Create test/unit/billing/credit_card_formatting_test.rb with tests for format_to_groups, clean_spaces, and card number masking
• [ ] Add test cases for all major card types: Visa, MasterCard, American Express, Discover, Diners Club, JCB
• [ ] Add edge case tests: invalid checksums, too-short/too-long numbers, special characters
• [ ] Verify test coverage reaches >90% for these modules using SimpleCov

• Add comprehensive spec/unit test coverage for lib/active_merchant/billing/response.rb—this class is referenced by all gateways but has minimal test visibility in the file list; start by writing tests for success/failure detection and message parsing.
• Write integration examples in examples/ directory for common multi-gateway scenarios (e.g., 'fallback from Stripe to Adyen if Stripe times out', 'log transaction details to database after purchase'). Currently only a code snippet exists in README.
• Add missing gateway implementation tests: several gateways in lib/active_merchant/billing/gateways/ (airwallex.rb, alelo.rb, allied_wallet.rb) appear to have recent additions but may lack corresponding test files; check for missing *_test.rb files and create them following the pattern in generators/gateway/templates/gateway_test.rb.

• High · Potential Credential Leakage in Gateway Implementations — lib/active_merchant/billing/gateways/ (all gateway implementations). The codebase contains numerous payment gateway integrations that handle sensitive financial data including API credentials, tokens, and card information. Multiple gateway files (adyen.rb, braintree.rb, authorize_net.rb, etc.) may store or process credentials without sufficient protection mechanisms. The widespread use of gateway configurations suggests potential for hardcoded secrets or insecure credential management patterns across 100+ payment gateway implementations. Fix: Implement strict credential management using environment variables or secure vaults (e.g., HashiCorp Vault, AWS Secrets Manager). Audit all gateway files for hardcoded secrets. Use .gitignore to prevent credential files from being committed. Implement automated scanning for exposed secrets in CI/CD pipeline.
• High · Sensitive Payment Data Exposure in Logging — lib/active_merchant/billing/gateway.rb, lib/active_merchant/billing/base.rb, lib/active_merchant/billing/gateways/. Payment processing libraries typically log request/response data for debugging. Given the size of this codebase (100+ gateways), there is a significant risk that credit card numbers, CVV codes, authorization tokens, or other PII may be logged unintentionally. The base gateway classes (gateway.rb, base.rb) and individual gateway implementations may not implement proper data masking/redaction. Fix: Implement comprehensive logging filters to redact sensitive data (PAN, CVV, SSN, tokens). Use PCI-DSS compliant logging practices. Never log full credit card numbers or authentication credentials. Implement structured logging with configurable verbosity levels.
• High · Missing Security Headers and TLS Configuration Validation — lib/active_merchant/billing/gateways/ (all implementations), lib/active_merchant/billing/gateway.rb. The codebase interacts with multiple external payment gateway APIs. There is no visible enforcement of secure TLS versions, certificate pinning, or validation of secure communication channels. The HTTP client configuration across 100+ gateways may not properly validate SSL/TLS certificates or enforce minimum TLS 1.2+. Fix: Enforce TLS 1.2 or higher minimum version across all gateway implementations. Implement certificate pinning for critical payment gateways. Validate SSL certificate chains properly. Use secure default HTTP client configurations. Regularly audit cipher suites used in API communications.
• Medium · Insufficient Input Validation on Financial Data — lib/active_merchant/billing/credit_card.rb, lib/active_merchant/billing/credit_card_methods.rb, lib/active_merchant/billing/check.rb. The credit card processing classes (credit_card.rb, credit_card_methods.rb) and payment data handlers may not perform sufficient validation on sensitive inputs. Potential for invalid card data, malformed amounts, or injection attacks through insufficiently validated user input before transmission to payment gateways. Fix: Implement strict input validation for all payment-related fields including card numbers (Luhn algorithm), CVV format, expiry dates, and monetary amounts. Use whitelisting rather than blacklisting. Validate data types and ranges. Implement rate limiting on validation endpoints.
• Medium · XML External Entity (XXE) Vulnerability Risk — lib/active_merchant/billing/gateways/cecabank/cecabank_xml.rb, lib/active_merchant/billing/gateways/ (XML-based gateways). Multiple gateway implementations parse XML responses from payment processors (evident from gateway file names like cecabank/cecabank_xml.rb, barclaycard_smartpay.rb, etc.). If XML parsing is not configured securely, the application is vulnerable to XXE attacks that could lead to information disclosure or denial of service. Fix: Disable XML external entity (XXE) processing in all XML parsers. Use nokogiri or similar libraries with XXE protection enabled. Configure parsers with Nokogiri::XML(data, options: {nonet: true}). Never use REXML without XXE protections disabled.
• Medium · Dependency Vulnerability Management Gap — Gemfile, gemfiles/ directory, activemerchant.gemspec. No dependency file (Gemfile.lock or gemfile.lock) was provided in the analysis. The project depends on Rails 4.2+ and potentially vulnerable transitive dependencies. Ruby ecosystem dependencies for payment processing are frequently targeted by security researchers and require regular updates. Fix: Maintain

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.