This page provides an overview of Drupal Commerce payments at a conceptual level. For step-by-step instructions for setting up payments for your site, see the Getting Started documentation. For more specific, technical explanations of the payments-related data structures and relationships, see Payments information structure documentation.
First, what are payment gateways? Payment gateways are a pluggable system that allows you to interface with a payment provider to handle the secure payment transactions for whatever you are selling. Amazon Pay, Authorize.net, Paypal, and Stripe are all examples of payment providers. The systems that send information about your orders off to your payment provider and handle responses from the payment provider are called payment gateways. These gateways are all unique because they have very different features and requirements.
There are two kinds of payment gateways that payment providers use: On-site and Off-site:
For a list of payment gateways currently supported by Drupal Commerce, see the Available payment gateways documentation.
The Drupal Commerce payment module also supports a third type of payment gateway: Manual. A manual payment gateway is one which does not interface with a payment provider. Instead, they can be used to allow payments made "in the real world". For example, a manual payment gateway could be created to provide a "Bill Me" option for pre-authorized customers. Those customers could complete their orders without paying and then pay by cash, check, bank transfer, etc. after receiving an invoice for the order.
On-site payment gateways define the types of payment methods that can be accepted. Drupal Commerce provides Credit card and PayPal payment method types, but custom payment gateways may define their own payment method types. So, what are payment methods then? In the case of the Credit card payment type, each individual credit card is a payment method. A single customer might have multiple credit cards (MasterCard, American Express, two different Visa cards, etc.), each of which will have its own number, expiration, security code, and associated customer data (like customer zip code).
If a payment gateway supports Stored payment methods, then your customers will be able to re-use their payment methods on future orders. Currently, stored payment methods are only supported within Drupal Commerce for On-site payment gateway types. However, work is currently underway to also allow Off-site payment gateways to use stored payment methods. See Issue #2838380: Allow offsite payment gateways to create and use payment methods.
Stored payment methods are displayed to customers as options during checkout. (See the Payments in the checkout process.) Customers can manage their stored payment methods through their User Account interface, located on your site at /user
. By default, stored payment methods can be added or deleted. Some payment gateways may also allow stored payment methods to be updated.
Payment providers accept payments from Drupal Commerce sites in the form of payment transactions, as defined by their specific APIs. Within Drupal Commerce sites, payments are created for each of these payment transactions to keep track of how much has been paid for each specific order. Each of these local payment records is linked to a remote payment transaction by the transaction's unique ID. In addition to the remote ID, local payment records also store the amount paid, the amount refunded, the remote state of the transaction, and the local state of the payment. The state options for a payment vary by the payment type; possible states include new, completed, and refunded.
When the Payments module is installed, the standard Billing information checkout pane is replaced by a Payment information pane. Additionally, a Payment process pane is provided. If the Payment information pane is disabled, then the Payment process pane is automatically disabled, since they are always used together. The standard Billing information pane only collects the information for the order's billing profile. Let's look at how the Payment information and Payment process panes work together to also collect and process payment information.
If multiple payment methods are available for the order, then the Payment information pane will display them as a radio button list. When the customer selects an option, the form is dynamically refreshed to collect information relevant to the payment method's payment gateway type:
In the following screenshot, there are several stored payment method options in addition to two options for creating new payment methods. When the Credit card payment option is selected, the credit card form is rendered to collect information to submit to the payment provider via the payment gateway. The billing profile form is also rendered at this time.
When the payment information checkout pane form is submitted, the payment gateway for the selected payment option and the information entered for the billing profile are saved to the order. If a stored payment method was selected, that payment method is also saved to the order. If the customer elected to create a new payment method, that payment method is created both locally and remotely and saved to the order (with a reference to the remote payment method).
Note that if the order has already paid or the order is free, then no payment information is collected; only the billing profile information is collected and saved to the order.
Following submission of the Payment information checkout pane, the customer will continue on to the Review step. If the customer clicks the Pay and complete purchase button, the Payment process checkout pane will be built to handle the actual payment process.
The payment process checkout pane has Transaction mode setting that can be set to either "Authorize and capture" or "Authorize only (requires manual capture after checkout)". Both On-site and Off-site gateways use this setting when creating the remote payment transaction through the payment provider's API. See the Payments administration section (below) for information on manually capturing payments after checkout.
The payment processing steps are:
Additional payments can be added to orders, and existing payments can be managed through the order administrative page, located at /admin/commerce/orders
. If an "Authorize only" payment transaction was created for the payment, then administrative users will be able to manually capture or void the transaction. A capture operation is a request to the payment provider to transfer the authorized payment amount from the customer's account to the merchant's account.
A payment transaction reaches the settled state when the payment transfer has completed (either automatically for an "Authorize and capture" payment transaction or manually for a capture operation). Typically, a payment transaction can be voided up until the transaction is settled. A void operation is a request to the payment provider to tell the card issuing bank that we don't intend to exercise the right to collect funds. After settlement, an administrative user can refund some or all of the payment transaction.
Found errors? Think you can improve this documentation?
edit this page