← Reference · Home · Print this page
Finance · Payments
ActiveMerchant (Ruby Payments Library)
Reference entry · last updated 20261020
Previous version, captured 20261020
ActiveMerchant is an open-source Ruby payment library extracted from Shopify. It provides a common interface to supported payment gateways and can be used in Rails or standalone Ruby applications.[1]
1. First principles: a gateway adapter
The library translates application calls into gateway-specific requests. A shared method name does not make all gateways support the same capabilities. The project maintains gateway-specific implementations and a supported-features table.[1]
2. Payment operations
The base gateway documents authorize, capture, purchase, void, and refund. Their arguments include amounts, payment credentials or authorization identifiers, and gateway options.[2]
| Operation | Meaning | Example |
|---|---|---|
authorize | Obtain approval and place a temporary hold.[3] | Reserve ₱2,000 when the order is placed. |
capture | Submit an existing authorization for collection.[3, 5] | Request collection of the reserved ₱2,000 when the order ships. |
purchase | Authorize and capture in one operation.[5] | Charge ₱2,000 at checkout. |
void | Cancel an authorization or another eligible transaction before settlement.[4] | Cancel the ₱2,000 payment before it settles, if eligible. |
refund | Return some or all of a collected payment.[4] | Return ₱500 for a returned item. |
Capture requests collection; settlement and payout follow. A successful capture does not mean the money has reached the merchant’s bank account. An authorization alone may appear as a pending charge.[3]
Void and refund eligibility depends on transaction state. For example, Braintree permits voids for Authorized or Submitted for Settlement transactions; Settling or Settled transactions require a refund. A captured payment may still qualify for a void. A successful void may take time to disappear from pending charges.[3, 4]
Supported operations, cancellation windows, refund eligibility, and timing depend on the gateway and payment method. A gateway’s support for partial or multiple captures must be checked separately.[1, 3, 4]
3. Amounts and responses
The README’s dollar example passes integer cents: 1000 represents USD 10.00. Its purchase example checks response.success? and reads response.message.[1]
4. Scope
ActiveMerchant is an integration library. Merchant acquiring arrangements, card-data security responsibilities, and dispute processes remain part of the payment system.
5. See also
- Online Payments
- Payment Service Providers (Merchant Payments)
- Card Authorization and Capture
- PCI DSS (Payment Card Data Security)