Broadleaf Microservices
  • v1.0.0-latest-prod

Environment Setup

Adding this module to your project

Once you have registered your account with Checkout.com, add the Broadleaf Checkout.com Maven dependency to your PaymentTransactionServices project.

<dependency>
    <groupId>com.broadleafcommerce.microservices</groupId>
    <artifactId>broadleaf-checkout-com</artifactId>
</dependency>
Note
 The dependency’s version will be pulled from the Broadleaf release train pom.xml.

Configuration

Required Properties

Gather the values of Public Key, Secret Key, and HMAC Signature Key from Checkout.com and populate following properties:

broadleaf:
  checkout-com:
    public-key: {Your Checkout.com Public Key}
    secret-key: {Your Checkout.com Secret Key}
    signature-key: {Your Checkout.com HMAC Signature Key}

Complete Configuration Reference

  • broadleaf.checkout-com.secret-key

    • Description: This secret key is the unique identifier provided by the Checkout.com which is used to authenticate with the Checkout.com SDK

  • broadleaf.checkout-com.public-key

    • Description: Along with the secret key, the public key is also used to authenticate with the Checkout.com SDK. Both of these keys needs to be provided in order to complete the authentication with Checkout.com

  • broadleaf.checkout-com.signature-key

    • Description: The HMAC is generated by taking the contents of the notification and hashing it using this key. The HMAC will be in every notification to validate the request. This key is required to integrate with the webhook.

  • broadleaf.checkout-com.environment

    • Description: Environment can be either PRODUCTION or SANDBOX. Sandbox Environment is required to test the SDK locally while Production Environment will be used on Production.

    • Default value: SANDBOX

  • broadleaf.checkout-com.expiration-duration

    • Description: The max duration of the Flow payment session before it expires.

    • Default Value: 24 hrs

    • Since Checkout.com library 2.1.0, Release Train 2.3.1

  • broadleaf.checkout-com.customer-retry-max-attempts

    • Description: The maximum number of authorization retry attempts for a Flow Payment Session, excluding the initial authorization. If on submission, the authorization of the payment method fails, the customer will be given additional attempts to add a payment via Flow. Flow will display error messages to the customer, with suggested next actions to improve retry success. Populates the customer retry max attempts property on the CreatePaymentSession API payload to create a Flow session.

    • Default Value: 5. The valid range for this property is [0-5].

    • Since Checkout.com library 2.1.0, Release Train 2.3.1

  • broadleaf.checkout-com.enable-stored-cards

    • Description: Whether or not to enable the stored cards consent collection in Flow. If true, sets the field payment_method_configuration.card.store_payment_details to collect_consent during the payment session create request to Checkout.com. This is set to false by default, giving preference to Checkout.com’s Remember Me functionality for saved payment methods. If enabled and consent is provided by the customer, then the payment’s Source ID will be included in the payment response, and can be stored with a Broadleaf saved payment method for future use.

    • Default Value: false

    • Since Checkout.com library 2.1.0, Release Train 2.3.1

  • broadleaf.checkout-com.enabled-payment-methods

    • Description: The list of payment method options to show on the payment form in Flow. If the same payment method is listed both here and in disabledPaymentMethods, this enabled list takes precedence and will override to display the payment. See the Checkout.com CreatePaymentSession API payload enabled_payment_methods property for reference.

    • Since Checkout.com library 2.1.0, Release Train 2.3.1

  • broadleaf.checkout-com.disabled-payment-methods

    • Description: The list of payment method options to hide on the payment form in Flow. If the same payment method is listed both here and in enabledPaymentMethods, the enabled list takes precedence and will override to display the payment. See the Checkout.com CreatePaymentSession API payload disabled_payment_methods property for reference.

    • Since Checkout.com library 2.1.0, Release Train 2.3.1

Note
 The properties under broadleaf.checkout-com.* (excluding broadleaf.checkout-com.gateway.*) are discriminated based on ContextInfo, see CheckoutConfigurationProperties and CheckoutComConfigurationPropertiesIT for example configurations.

Cart Operation Service Configuration

Add the following properties to declare the CHECKOUT_COM gateway as an available payment method.

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-payment-method-options:
          - payment-method-type: CREDIT_CARD
            payment-method-gateway-type: CHECKOUT_COM

CHECKOUT_COM should be added to the following property to declare when transactions for this gateway should be executed, relative to other gateways, during checkout processing.

broadleaf:
  cartoperation:
    service:
      checkout:
        payment-gateway-priorities:
          - ...
          - CHECKOUT_COM
          - ...

By default, Authorize transactions are executed by CartOps during checkout. If you wish to execute AuthorizeAndCapture transactions instead, define the following property:

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-transaction-types:
          CHECKOUT_COM: AUTHORIZE_AND_CAPTURE
Note

This property is application-discriminated, allowing different values to be provided on a per-tenant or per-application basis using the following property paths:

  • broadleaf.cartoperation.service.checkout.tenant.mytenant.checkout-transaction-types.CHECKOUT_COM=AUTHORIZE_AND_CAPTURE

  • broadleaf.cartoperation.service.checkout.application.myapplication.checkout-transaction-types.CHECKOUT_COM=AUTHORIZE_AND_CAPTURE

"mytenant" & "myapplication" being the Broadleaf Tenant and Application ids.

Configuration for OrderOperationServices

CHECKOUT_COM should be added to the following property to declare when ReverseAuthorize or Refund transactions for this gateway should be executed, relative to other gateways, when cancelling a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        cancel-payment-gateway-priorities:
          - ...
          - CHECKOUT_COM
          - ...

CHECKOUT_COM should be added to the following property to declare when Capture transactions for this gateway should be executed, relative to other gateways, when capturing payment for a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        capture-payment-gateway-priorities:
          - ...
          - CHECKOUT_COM
          - ...

CHECKOUT_COM should be added to the following property to declare when Refund transactions for this gateway should be executed, relative to other gateways, when refunding payment for a fulfillment return.

broadleaf:
  orderoperation:
    service:
      payment:
        refund-payment-gateway-priorities:
          - ...
          - CHECKOUT_COM
          - ...

Configuring Webhooks to Understand Transaction Results

To understand the results for Capture, Refund, & Reverse-Authorize (Void) transactions, Checkout.com requires that you leverage webhooks. The webhooks can be setup & configured in the Checkout.com admin hub using the following steps:

  • Go to Settings → Channels.

  • Select "New Webhook" from the Webhook Section.

  • Enter your endpoint url where you want to receive webhook notifications.

  • Note: This url should point to PaymentTransactionService’s webhook-handling endpoint.

  • Select event types and then select Create to complete the configuration.

The following event types supported by default:

  • payment_approved

  • payment_declined

  • payment_captured

  • payment_capture_declined

  • payment_refunded

  • payment_refund_declined

  • payment_voided

  • payment_void_declined

If you need to add the support for other events you have to implement the com.broadleafcommerce.payment.service.gateway.constants.CheckoutComWebhookType interface and override com.broadleafcommerce.payment.service.gateway.webhooks.DefaultCheckoutComGatewayWebhookHandler.getWebhookType to return your implementation.

For example:

    public enum MyWebhookTypesEnum implements CheckoutComWebhookType {

        PAYMENT_CANCELED("payment_canceled", "Void", true);

        private final String webhookType;
        private final String transactionType;
        private final boolean isSuccessful;

        WebhookTypesEnum(String webhookType, String transactionType, boolean isSuccessful) {
            this.webhookType = webhookType;
            this.transactionType = transactionType;
            this.isSuccessful = isSuccessful;
        }

        @Override
        public TransactionType toBroadleafTransactionType() {
            // PAYMENT_CANCELED is equivalent of REVERSE_AUTH in Broadleaf
            if (this == PAYMENT_CANCELED) {
                return DefaultTransactionTypes.REVERSE_AUTH;
            }

            return EnumUtils.getEnumIgnoreCase(DefaultTransactionTypes.class, transactionType);
        }
    }

    ...

    @Nullable
    @Override
    protected CheckoutComWebhookType getWebhookType(
            @lombok.NonNull CheckoutComWebhookResponse webhookResponse) {
        CheckoutComWebhookType type = super.getWebhookType(webhookResponse);
        return type != null ? type : EnumUtils.getEnumIgnoreCase(MyWebhookTypesEnum.class,
                webhookResponse.getType());
    }