This page provides specific, technical explanations of the payment-related data structures and relationships in Drupal Commerce. Familiarity with Drupal concepts including configuration entities, content entities, fields, and plugins is assumed. For a more general introduction to Drupal Commerce payments, see the Payments documentation page. For step-by-step instructions for setting up payments for your site, see the Getting started documentation.
A payment gateway is a configuration entity that manages a single instance of a payment gateway plugin. Payment gateways are created and managed through the adminstrative UI (or programatically). Customers interact with payment gateways only indirectly, when they select a payment option during checkout. See the Payment options builder section for additional information. Payment gateway plugins provide the functionality that allows customers to enter their payment information, interact with the payment providers that capture the actual payments, and update order information locally to correctly track whether orders have been paid. See the Creating payment gateways documentation for information about payment gateway plugins.
Payment, payment method, and order entities all have a payment gateway entity reference field.
Field | Description |
---|---|
id | Unique string id for the gateway |
label | Name of the gateway, for administrative use only |
weight | Used for ordering payment gateways |
conditions | An array of \Drupal\commerce\Plugin\Commerce\Condition\ConditionInterface condition plugins, see Core Conditions documentation |
condition_operator | The condition operator: AND or OR , a string |
plugin | The payment gateway plugin |
configuration | An array of plugin configuration, see Payment gateways: Getting started documentation |
status | Whether the plugin gateway is enabled or disabled |
A payment is a content entity that stores local information about payment transactions that are executed remotely. These payment transactions may be submitted to a payment provider via its API or they may be payments that are received "in the real world" (cash, check, etc.) Every payment belongs to a single Drupal Commerce order and a single payment gateway. Payments are created by payment gateway plugins; each payment gateway plugin defines the payment type for the payments it creates.
Out of the box, the Commerce Payment module provides two payment types: payment_default
and payment_manual
. The manual payment type is used for manual payment gateways; default is used, by default, by all other payment gateways. Each payment type has its own workflow, which defines the states and transitions for a payment's status.
Default payment types have the following payment transaction statuses:
State Id | Label | Description |
---|---|---|
new | New | The initial state for any new payment. |
authorization | Authorization | If the payment gateway supports authorizations, payments will typically transition from New to Authorization. |
completed | Completed | If the payment gateway supports authorizations, payments will typically transition from Authorization to Completed, once the transaction is "captured". For other payment gateways, payments will typically transition directly from New to Completed. Only amounts for payments that have been completed are added to the order's total paid amount. |
authorization_voided | Authorization (Voided) | If the payment gateway supports voids, a payment can transition from Authorization to Authorization (Voided). |
authorization_expired | Authorization (Expired) | If the payment gateway supports authorizations, a payment can transition from Authorization to Authorization (Expired). |
partially_refunded | Partially refunded | If the payment gateway supports refunds, a payment can transition from Completed to Partially refunded. |
refunded | Refunded | If the payment gateway supports refunds, a payment can transition from either New or Partially refunded to Refunded. |
Manual payment types have the following payment transaction statuses:
State Id | Label | Description |
---|---|---|
new | New | The initial state for any new payment. |
pending | Pending | When a payment is created, typically at the final checkout confirmation step, it transitions from New to Pending. |
completed | Completed | Once the payment transaction is "received", the payment transitions from Pending to Completed. |
voided | Voided | If a payment transaction is not going to be received, the payment can transition from Pending to Voided. |
partially_refunded | Partially refunded | If the payment gateway supports refunds, a payment can transition from Completed to Partially refunded. |
refunded | Refunded | If the payment gateway supports refunds, a payment can transition from either New or Partially refunded to Refunded. |
Field | Description |
---|---|
payment_id | Unique numeric id for the payment |
type | String id for the payment type plugin; core types are payment_default and payment_manual . |
payment_gateway | String id for the payment gateway, required |
payment_gateway_mode | String id for the payment gateway mode, required; default types are test and live . |
payment_method | Id of the payment method (On site payment gateways) |
order_id | Id of the parent order |
remote_id | Remote id for the payment, a string up to 255 characters long |
remote_state | Remote payment state, a string up to 255 characters long |
amount | The payment amount, with currency, required |
refunded_amount | The refunded amount, with currency |
state | The status of the payment, a string corresponding to a workflow state, required |
authorized | The time when the payment was authorized, (i.e., when the payment's state is set to authorization ) |
expires | The time when the payment expires, 0 for never |
completed | The time when the payment was completed, (i.e., when the payment's state is set to completed ) |
Field | Description |
---|---|
id | Unique string id for the payment type |
label | The payment type label, for administrative use only |
workflow | The payment workflow, default is payment_default ; Manual payment types use payment_manual |
Payments are created during checkout when a customer confirms his order and can be created manually through the administrative UI. See the Code recipes documentation for an example of creating a payment programatically. For Manual and On-site payment gateway plugins, payments are created by the createPayment()
method. For Off-site payment gateway plugins, payments are typically created in the onReturn()
method or in the onNotify()
method, if the gateway supports asynchronous notifications (IPNs).
A payment method is a content entity that stores local information for a payment method created and stored remotely by a payment provider. Credit card and Paypal are two types of payment methods, both of which are provided by the core Commerce Payment module. Payments can be created from payment methods. Currently, payment methods are only available for On site payment gateways that support stored payment methods. Payment methods belong to customers and can generally be re-used for multiple orders.
Payment gateways define the types of payment methods they support. For example, the Commerce Braintree payment gateway supports credit_card
, paypal
, and paypal_credit
payment method types. A payment method type defines the information to be collected and stored locally whenever a payment method is created. For example, for credit_card
payment methods, Card type and Card number (last few digits only) are required fields; Card expiration month and Card expiration year are additional fields that can be optionally used for credit card payments.
Field | Description |
---|---|
id | Unique numeric id for the payment method |
type | String id for the payment method type plugin; core types are credit_card and paypal |
uid | Numeric id for the payment method owner |
payment_gateway | String id for the payment gateway, required |
payment_gateway_mode | String id for the payment gateway mode, required; default types are test and live . |
remote_id | Remote id for the payment method, a string up to 255 characters long |
billing_profile | Numeric id for the billing profile |
reusable | Whether the payment method is reusable, default value is TRUE |
is_default | Whether the payment method is the user's default payment method |
expires | The time when the payment method expires, 0 for never |
created | The time when the payment method was created |
changed | The time when the payment method was last edited |
One standard field that's not listed as a payment method field is, "label". That's because the label for a payment method is actually generated by its payment method type's plugin method. All payment method type plugins must implement the buildLabel()
method. For example, the credit card payment method type builds labels that look like, "Visa ending in 1111" or "Mastercard ending in 0004". For the PayPal payment method type, labels look like "PayPal (mymail@example.com)".
Field | Description |
---|---|
id | Unique string id for the payment method type |
label | The payment method type main label, for administrative use |
create_label | The label displayed to customers when the payment method is included in a list of payment options, defaults to the main label |
Payment methods are created by payment gateway plugins that implement SupportsStoredPaymentMethodsInterface
. During checkout, when a customer selects a payment option provided by an On site gateway, he is prompted to enter payment details which are transmitted to the payment provider. If the request is successful, a payment method entity is created locally by the payment gateway's createPaymentMethod()
method, and that payment method is attached to the customer and the order. See also the Code recipes documentation for an example of creating a payment method programatically.
The PaymentOptionsBuilder
service ties together all the internally stored payment gateway and payment method information to provide the list of "Payment methods" the customer sees during checkout. (If only one payment method is available, it is set automatically; the customer won't see a list of options.) These options can come from a variety of sources:
The customer's stored payment methods. If a customer created payment methods for previous orders, and they are reusable and applicable to the current order, they will be displayed as options. The labels used for these options are generated based on the payment method type.
The payment method for the order. If a payment method has already been added to the order, it will be displayed as one of the options. Its label is also generated based on its payment method type.
Options to create new payment methods for applicable payment gateways. For example, if the "Credit card", "PayPal", and "PayPal Credit" payment method options are all enabled for the Commerce Braintree payment gateway, then they will also appear as options. The payment method type's create_label
is used for the labels.
display_label
is used for the labels.These options appear on the "Payment information" checkout pane that is typically part of the "Order Information" step.
To manage all this information, PaymentOption
objects are used, with the following structure:
Field | Description |
---|---|
id | Unique string id for the payment option |
label | The payment option label that's displayed to customers |
paymentGatewayId | The payment gateway ID, a string |
paymentMethodId | The payment method ID, when known, a string |
paymentMethodTypeId | The payment method ID, when known, a string |
Found errors? Think you can improve this documentation?
edit this page