Gateways vs. Integrations - activemerchant/active_merchant GitHub Wiki

Active Merchant (AM) has two main types of payment flow process

The Gateway process is the “normal” process where the application is assumed to have already collected all the customer address and payment details. The application makes a (secure) direct request to the payment provider and passes these details. The result from the payment provider will directly indicate success or failure of the transaction against that card.

AM supports several main operations against card details:

• Authorize(money, creditcard, options = {}) (note US spelling)
  • Validate the credit card and reserve the money for later collection
• Capture(money, authorization, options = {})
  • References a previous “Authorize” and requests that the money be drawn down. It’s good practice (required) in many juristictions not to take a payment from a customer until the goods are shipped
• Purchase(money, creditcard, options = {})
  • This is combined Authorize and Capture in one transaction. Sometimes we just want to take a payment!
• Credit(money, identification, options = {})
  • Refund money to a card. This may need to be specifically enabled on your account and may not be supported by all gateways
• Void(identification, options = {})
  • Entirely void a transaction.

An Integration is something like Paypal standard where the process is essentially to create a carefully crafted post request that we send back to the user’s browser and they in turn submit that directly to the provider (often using javascript). The provider will then use those details to charge the customer and redirect back to your site. Usually there is some form of out of band notification back to your site (eg Paypal IPN) that the payment has been made and amount collected, etc, but at the very least you should be careful to validate that the payment matches expectation and that the payment process has not been subverted.

Again AM assumes that you have already collected billing details excluding CC info.

• AM Provides a helper method to assist in generating the redirect form.
• Your application then returns this form to the user (eg if using rails it will be part of your generated page output)
• The user is then redirected to the payment processor who will collect payment details, etc
• Frequently there is then an out of band check back to your site, ie some kind of “IPN” where the payment processor will contact a known URL and pass in all the payment details and ask your application to confirm that these details match the expected amounts, etc. This gives you a) security against the payment process being subverted and b) notification that the payment process has been completed
• Finally the payment provider will redirect the customer back to your site at either a success/failure URL of your choice. This can be used to show a “Payment completed” type message and/or to note that the payment has been completed. Normally give the customer some kind of reference to the transaction at this point in case of any follow questions

With the gateway there is clearly much more flexibility, but the onus rests on the user application to collect the CC details and to pass the PCI compliance requirements that come along with handling card details (At the minimum these include requiring end to end encryption of all card details and submitting your application for regular PCI compliance scans. However, these rules are tightening rapidly and the burden of compliance is becoming quite substantial.

The Integration approach offers quite a number of benefits for the smaller merchant as there are frequently no compliance requirements if you don’t touch the card details at all. Do however note that there are a few hybrid style gateways where you can outsource the actual collection of the card details to the gateway – these are technically Gateways but have low/no PCI compliance requirements. Paypal Express Checkout is an example and Protx Server would be a potential example (were it implemented in AM)