You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: user/pages/03.commerce2/02.developer-guide/05.payments/04.payments-information-structure/docs.md
+152-5
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,156 @@ taxonomy:
4
4
category: docs
5
5
---
6
6
7
-
! We need help filling out this section! Feel free to follow the *edit this page* link and contribute.
7
+
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](../../getting-started).
- payment options, credit card / credit card type objects
12
-
- payment order manager, payment statuses
9
+
#### Payment gateways
10
+
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](#payment-options-builder) 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](../create-payment-gateway) for information about payment gateway plugins.
11
+
12
+
Payment, payment method, and order entities all have a payment gateway entity reference field.
13
+
14
+
####Payment gateway fields
15
+
16
+
| Field | Description |
17
+
| ---------- | ----------- |
18
+
| id | Unique string id for the gateway |
19
+
| label | Name of the gateway, for administrative use only |
20
+
| weight | Used for ordering payment gateways |
21
+
| conditions | An array of `\Drupal\commerce\Plugin\Commerce\Condition\ConditionInterface` condition plugins, see [Core Conditions documentation](../../core/conditions)|
22
+
| condition_operator | The condition operator: `AND` or `OR`, a string |
23
+
| plugin | The payment gateway plugin |
24
+
| configuration | An array of plugin configuration, see [Payment gateways: Getting started documentation](../create-payment-gateway/getting-started)|
25
+
| 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.
31
+
32
+
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.
33
+
34
+
##### Payment states
35
+
**Default** payment types have the following payment transaction statuses:
| new | New | The initial state for any new payment.
40
+
| authorization | Authorization | If the payment gateway supports authorizations, payments will typically transition from New to Authorization. |
41
+
| 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. |
42
+
| authorization_voided | Authorization (Voided) | If the payment gateway supports voids, a payment can transition from Authorization to Authorization (Voided). |
43
+
| authorization_expired | Authorization (Expired) | If the payment gateway supports authorizations, a payment can transition from Authorization to Authorization (Expired). |
44
+
| partially_refunded | Partially refunded | If the payment gateway supports refunds, a payment can transition from Completed to Partially refunded. |
45
+
| refunded | Refunded | If the payment gateway supports refunds, a payment can transition from either New or Partially refunded to Refunded. |
46
+
47
+
**Manual** payment types have the following payment transaction statuses:
| new | New | The initial state for any new payment.
52
+
| pending | Pending | When a payment is created, typically at the final checkout confirmation step, it transitions from New to Pending. |
53
+
| completed | Completed | Once the payment transaction is "received", the payment transitions from Pending to Completed. |
54
+
| voided | Voided | If a payment transaction is not going to be received, the payment can transition from Pending to Voided. |
55
+
| partially_refunded | Partially refunded | If the payment gateway supports refunds, a payment can transition from Completed to Partially refunded. |
56
+
| refunded | Refunded | If the payment gateway supports refunds, a payment can transition from either New or Partially refunded to Refunded. |
57
+
58
+
##### Payment fields
59
+
| Field | Description |
60
+
| --------------- | ----------- |
61
+
| payment_id | Unique numeric id for the payment |
62
+
| type | String id for the payment type plugin; core types are `payment_default` and `payment_manual`. |
63
+
| payment_gateway | String id for the payment gateway, required |
64
+
| payment_gateway_mode | String id for the payment gateway mode, required; default types are `test` and `live`. |
65
+
| payment_method | Id of the payment method (On site payment gateways) |
66
+
| order_id | Id of the parent order |
67
+
| remote_id | Remote id for the payment, a string up to 255 characters long |
68
+
| remote_state | Remote payment state, a string up to 255 characters long |
69
+
| amount | The payment amount, with currency, required |
70
+
| refunded_amount | The refunded amount, with currency |
71
+
| state | The status of the payment, a string corresponding to a workflow state, required |
72
+
| authorized | The time when the payment was authorized, (i.e., when the payment's state is set to `authorization`) |
73
+
| expires | The time when the payment expires, 0 for never |
74
+
| completed | The time when the payment was completed, (i.e., when the payment's state is set to `completed`) |
75
+
76
+
##### Payment type properties
77
+
| Field | Description |
78
+
| ---------- | ----------- |
79
+
| id | Unique string id for the payment type |
80
+
| label | The payment type label, for administrative use only |
81
+
| workflow | The payment workflow, default is `payment_default`; *Manual* payment types use `payment_manual`|
82
+
83
+
##### Creating payments
84
+
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](../code-recipes) 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).
85
+
86
+
##### Saving payments
87
+
- When a payment is saved, the payment gateway mode is automatically set, based on the current mode for its payment gateways's plugin.
88
+
- Authorized and completed timestamps are updated automatically.
89
+
- When a payment is saved, the total paid amount for the payment's order is updated.
90
+
91
+
##### Deleting payments
92
+
- When a payment is deleted, the total paid amount for the payment's order is updated.
93
+
94
+
#### Payment methods and payment method types
95
+
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.
96
+
97
+
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.
| type | String id for the payment method type plugin; core types are `credit_card` and `paypal`|
106
+
| uid | Numeric id for the payment method owner |
107
+
| payment_gateway | String id for the payment gateway, required |
108
+
| payment_gateway_mode | String id for the payment gateway mode, required; default types are `test` and `live`. |
109
+
| remote_id | Remote id for the payment method, a string up to 255 characters long |
110
+
| billing_profile | Numeric id for the billing profile |
111
+
| reusable | Whether the payment method is reusable, default value is `TRUE`|
112
+
| is_default | Whether the payment method is the user's default payment method |
113
+
| expires | The time when the payment method expires, 0 for never |
114
+
| created | The time when the payment method was created |
115
+
| changed | The time when the payment method was last edited |
116
+
117
+
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 ([email protected])".
118
+
119
+
##### Payment method type properties
120
+
| Field | Description |
121
+
| ------------ | ----------- |
122
+
| id | Unique string id for the payment method type |
123
+
| label | The payment method type main label, for administrative use |
124
+
| create_label | The label displayed to customers when the payment method is included in a list of payment options, defaults to the main label |
125
+
126
+
##### Creating payment methods
127
+
*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](../code-recipes) for an example of creating a payment method programatically.
128
+
129
+
##### Saving payment methods
130
+
- When a payment method is saved, the payment gateway mode is automatically set, based on the current mode for its payment gateways's plugin.
131
+
132
+
#### Payment options builder
133
+
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:
134
+
135
+
1. 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.
136
+
137
+
2. 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.
138
+
139
+
3. 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.
140
+
141
+
4. Options for applicable payment gateways that do not provide payment methods (off-site, manual, etc). The payment gateway plugin's `display_label` is used for the labels.
142
+
143
+
These options appear on the "Payment information" checkout pane that is typically part of the "Order Information" step.
144
+
145
+
146
+
147
+
To manage all this information, `PaymentOption` objects are used, with the following structure:
148
+
149
+
##### Payment option properties
150
+
| Field | Description |
151
+
| -------------------- | ----------- |
152
+
| id | Unique string id for the payment option |
153
+
| label | The payment option label that's displayed to customers |
154
+
| paymentGatewayId | The payment gateway ID, a string |
155
+
| paymentMethodId | The payment method ID, when known, a string |
156
+
| paymentMethodTypeId | The payment method ID, when known, a string |
0 commit comments