broadleaf:
cartoperation:
service:
checkout:
payment-gateway-priorities:
- PAYPAL
- CYBERSOURCE
- AMAZON_PAYMENT_SERVICES
- STRIPE
- v1.0.0-latest-prod
As of 1.7, payment data storage and interactions have been moved to the Payment Transaction Services and the payments were removed from the Cart.
Introduced the new PaymentSummary domain to replace the Payment status concept. This domain summarizes the current state of transactions against the payment.
There are two new external providers to interact with the Payment Transaction Service Payment Provider.
To ensure that a payment cannot be updated while checkout is in progress the checkout uses payment locking concept.
The lock tokens pass throughout the workflow and other DefaultCheckoutService methods, so that any payment-modifying requests can make use of the existing lock.
When executing transactions against payments on a Cart, they are sorted based on configured priority based on payment gateway types. In some cases, the sorting order of the payments may matter.
For example, transactions through certain payment gateways may be more challenging to reverse than others if the checkout workflow is rolled back. Let’s say we have two payment gateways, G1 and G2, and G1 is more challenging to reverse the payments than G2. Let’s say we also prioritized G2 payments to execute ahead of G1 payments. In this case, if there’s a problem authorizing G1 payments after G2 payments have already been authorized, then we’re faced with a more favorable transaction reversal scenario using G2.
To allow customizations of the payment sorting order, a hook point has been added for the transaction execution in CartOperationServices:
DefaultPaymentTransactionExecutionService#sortPaymentsByPriority
By default, this method delegates to PaymentPriorityStrategy.java to sort the payments based on the payment gateway type, which can be configured in the Configuration section.
It is crucial to understand that the list of payment gateways for the property is ordered. Payment gateway type that is placed at the first of the list will be the highest priority.
Property: broadleaf.cartoperation.service.checkout.payment-gateway-priorities
Contains the ordered list of payment gateway types
To retrieve the list of payment method options as a frontend client, call the Get payment method options endpoint, which uses the CheckoutPaymentMethodService#getCheckoutPaymentMethodOptions to get the list of applicable payment methods.
This provides an array of payment method options, detailing the type and gateway type, that are available for the customer.
broadleaf.cartoperation.service.checkout.checkout-payment-method-options: A list of configured payment method options that are available during checkout.
It has the following properties:
payment-method-type: The type of method such as CREDIT_CARD or COD
payment-method-gateway-type: The specific payment gateway to configure, e.g., PASSTHROUGH.
cart-max-total-restriction: The maximum cart total for which the payment is allowed to be used. This is a map where the key is the currency code and the value is the amount.
cart-min-total-restriction: The minimum cart total for which the payment is allowed to be used. This is a map where the key is the currency code and the value is the amount.
fulfillment-inclusions: List of inclusion criteria to compare against a FulfillmentGroup to determine if this payment option is allowed.
The key is the path of the field to compare with on the group.
The value is the list of valid values.
Example values:
address.country: ['US', 'UK', 'CA']
fulfillmentOption.name: ['STANDARD', 'PRIORITY', 'EXPRESS']
fulfillmentExclusions: Like fulfillment-inclusions but for providing excluded values instead.
fees: A list of applicable fees for the this payment option. Can be discountable and/or taxable.
Note: Will only be applied in the case of Collect on Delivery (COD) type payments by default. We will eventually extend out of box support to any payment option.
Properties:
name: Used to identify the fee after it is applied to make sure that it is not double added and is easily removed if the payment method changes.
amount: Decimal amount to charge
currency: The currency code
discountable: Whether it can be discounted.
taxable: Whether it can be taxed. Some fees may already include tax.
refundable: Whether it can be refunded.
broadleaf.cartoperation.service.checkout.tenant.{MY_TENANT}.checkout-payment-method-options
Tenant-discriminated property for broadleaf.cartoperation.service.checkout.checkout-payment-method-options
broadleaf.cartoperation.service.checkout.application.{MY_APPLICATION}.checkout-payment-method-options
Application-discriminated property for broadleaf.cartoperation.service.checkout.checkout-payment-method-options
|
Note
|
If using properties discriminated by tenant or application, the list of payment method options provided will override the list of payment method option properties without any tenant/application discrimination. Be sure to re-include all gateways permitted for that tenant/application. See example below. |
broadleaf:
cartoperation:
service:
checkout:
# global default
checkout-payment-method-options:
- payment-method-type: CREDIT_CARD
payment-method-gateway-type: STRIPE
# application specific
application:
# the keys are the IDs of the applications
some-application-id:
checkout-payment-method-options:
- payment-method-type: CREDIT_CARD
payment-method-gateway-type: STRIPE
- payment-method-type: ACCOUNT_CREDIT
payment-method-gateway-type: BLC_ACCOUNT_CREDIT_GATEWAY
- payment-method-type: COD
payment-method-gateway-type: COD
cart-max-total-restriction:
USD: 500.00
cart-min-total-restriction:
USD: 100.00
fulfillment-inclusions:
fulfillmentOption.name: ['FIXED_STANDARD']
fulfillment-exclusions:
address.postalCode: ['10100']
fees:
- name: Fee 1
amount: 1.00
currency: USD
taxable: false
discountable: false
refundable: falseTo support customizations of the availability of payment method options by customer, cart, or context attributes, several hookpoints were added in CheckoutPaymentMethodService.
CheckoutPaymentMethodService#filterAvailableCheckoutPaymentMethodOptionsByCustomer
CheckoutPaymentMethodService#filterAvailableCheckoutPaymentMethodOptionsByCart
By default, these hooks return the unmodified list of payment method options.
The payment method option lookup was also added in CartPaymentMethodValidationActivity to validate that all the payment options on the cart during this checkout are valid for the customer.
To enable this validation, set broadleaf.cartoperation.service.checkout.checkout-payment-method-validation-enabled to true.