Broadleaf Microservices
  • v1.0.0-latest-prod

Release Notes for 1.0.2-GA

Requirements

  • JDK 11 is now required for Broadleaf release trains 1.7.0-GA, and beyond.

New Features & Notable Changes

Feature/Notable Change Related Services Links

Introduced SavedPaymentMethod to store and manage saved payment data in PaymentTransactionServices

CustomerServices, AuthenticationServices, PaymentGatewayCommon

Refined the process of saved payment method creation to be executed after the first transaction execution (Authorize or Authorize and capture transactions)

CustomerServices

Introduced and deprecated CreateSavedPaymentMethodEventListener to support the transitional period of the saved payment method migration

Add a hook in the "create saved payment" logic, so that a single-use token can be swapped for a multi-use token via a gateway-specific interaction and the new token can be stored to SavedPaymentMethod#paymentMethodProperties

Introduced anonymization support for customer-owned saved payment methods

Updated the process for identifying & processing transactions that require reversal

CartOperationServices

Introduced support for gathering payment gateway transaction results via webhook interactions

Introduced several mechanisms to help look up & record transaction results following 3DS verification

Introduced new owningUserType and owningUserId fields to Payment to indicate the owning user of the payment

Introduced recording of the payment gateway’s transaction id & message for each payment transaction

Update how customer access restrictions are declared for payments to simplify the interaction for other services

CartOperationServices

Added ownership validation to ensure that anonymous customer cannot access payments that belong to a registered customer

Upgrade Guide

API Changes

PaymentTransactionServices OpenAPI Docs

New Endpoints

Path Description

GET /customers/{customerId}/saved-payment-methods

Read customer’s saved payment methods

POST /customers/{customerId}/saved-payment-methods

Create saved payment method for customer

GET /customers/{customerId}/saved-payment-methods/{savedPaymentMethodId}

Read saved payment method

PATCH /customers/{customerId}/saved-payment-methods/{savedPaymentMethodId}

Update saved payment method

DELETE /customers/{customerId}/saved-payment-methods/{savedPaymentMethodId}

Delete saved payment method

POST /payment-transactions/{paymentId}/claim-transactions-for-request

Claim a payment’s transactions for the provided request id

DELETE /pii/payments/{customerId}

Anonymize a customer’s payments

PATCH /payments/block-customer-mutability

Block Customer mutability Of payments

PATCH /payments/transfer-to-csr

Transfer payment ownership to a CSR

PATCH /payments/transfer-from-csr

Transfer payment ownership from a CSR to a customer

POST /payment-transactions/{paymentId}/claim-transactions-for-request

Claim payment transactions for a request id

POST /handle-3ds-transaction-result/{gatewayType}

Record 3DS payment transaction results

GET /lookup-3ds-transaction-result/{paymentId}

Look up & record 3DS payment transaction results

POST /webhooks/{gatewayType}

Handle payment gateway webhook interactions

Endpoint Updates

Path Description of Changes

POST /payments/lock

Permission roots were changed to PAYMENT_LOCK_MANAGEMENT.

Note: The legacy permission root of SYSTEM_PAYMENT_MANAGEMENT can continue to be used.

POST /payments/unlock

POST /payments/{id}/lock

POST /payments/{id}/unlock/{token}

Endpoint Deprecations

Path Notes

GET /sensitive-payments

Deprecated in favor of using PaymentTransactionServices to manage saved payment methods.

Schema Changes & Data Migrations

Liquibase Change Sets

Create/Update SQL

Drop SQL

Saved Payment Method Data Migrations

If the storage location of saved payment methods are changed from CustomerServices to PaymentTransactionServices, the data needs to be moved from customer.blc_payment_account to paymenttransaction.blc_saved_payment_method, which can be accomplished using the following migration queries once the tables are created.

Important
 Even though storing and managing saved payment methods via CustomerServices is still supported, it is deprecated and PaymentTransactionServices should be used instead
Options for Executing the Migrations

There are two options for how to do the data migration:

  1. Run the Migration Scripts via Liquibase

    • This option is quite simple, but requires that the customer and paymenttransaction schemas all reside in the same database server, and therefore, Liquibase can effectively access each schema.

  2. Run the Migration Scripts via DBA Interaction

    • If the schemas reside in different database servers, then the migration needs to be executed via DBA interaction. These steps might look like:

      1. Copy the table from the customer schema into the paymenttransaction schema

      2. Run the same scripts, referencing the paymenttransaction schema, instead of the customer schema

Migrating PaymentAccounts from CustomerServices to PaymentTransactionServices

To migrate the data from customer.blc_payment_account to paymenttransaction.blc_saved_payment_method, we can use the following migration scripts, once the tables are created.

Migrating PaymentAccounts
INSERT INTO "paymenttransaction".blc_saved_payment_method
(ID, OWNING_USER_TYPE, OWNING_USER_ID, NAME, ORIGINATING_PAYMENT_ID, TYPE, GATEWAY_TYPE, PAYMENT_METHOD_PROPERTIES, ATTRIBUTES, DISPLAY_ATTRIBUTES, IS_DEFAULT_FOR_OWNER, LAST_TX_DATE_TIME, LAST_TX_RESULT_CODE, VERSION, TRK_ARCHIVED, AUDIT_CREATOR, AUDIT_CREATION_TIME, AUDIT_UPDATER, AUDIT_UPDATE_TIME, TRK_TENANT_ID, BILLING_ADDRESS)

SELECT pa.ID, 'BLC_CUSTOMER', pa.CUSTOMER_ID, pa.DISPLAY_NAME, pa.ORIGINATING_PAYMENT_ID, COALESCE(pa.ACCOUNT_TYPE, 'CREDIT_CARD'), pa.GATEWAY_TYPE, pa.PAYMENT_GATEWAY_PROPERTIES, '{}', COALESCE(pa.DISPLAY_ATTRIBUTES, '{}'), 'N', pa.LAST_TRANSACTION_DATE_TIME, pa.LAST_BILLING_TRANSACTION_RESULT_CODE, 1, pa.DEACTIVATED, pa.AUDIT_CREATOR, pa.AUDIT_CREATION_TIME, pa.AUDIT_UPDATER, pa.AUDIT_UPDATE_TIME, COALESCE(pa.TRK_TENANT_ID, 'UNKNOWN_TENANT_ID'), CONCAT('{"fullName":"', pa.FULL_NAME, '","addressLine1":"', pa.ADDRESS_LINE_1, '","addressLine2":"', COALESCE(pa.ADDRESS_LINE_2, ''), '","addressLine3":"', COALESCE(pa.ADDRESS_LINE_3, ''), '","city":"', pa.CITY, '","stateProvinceRegion":"', pa.STATE_PROVINCE_REGION, '","county":"', pa.COUNTY, '","country":"', pa.COUNTRY, '"', ',"postalCode":"', pa.POSTAL_CODE, '","phonePrimary":', COALESCE(pa.PHONE_PRIMARY, '{}'), ',"phoneSecondary":', COALESCE(pa.PHONE_SECONDARY, '{}'),'}')
FROM "customer".blc_payment_account pa;
Updating Default Saved Payment Methods

Once the saved payment data is migrated, run the following script to update the default saved payment methods:

UPDATE "paymenttransaction".blc_saved_payment_method sp
SET IS_DEFAULT_FOR_OWNER = 'Y'
FROM "customer".blc_customer c
WHERE sp.id = c.DEFAULT_PAYMENT_ACCOUNT_ID;
Default Values

The following fields have the corresponding default values:

  • OWNING_USER_TYPE: BLC_CUSTOMER

  • OWNING_USER_ID: customer’s id

  • ATTRIBUTES: {} (empty map)

  • DISPLAY_ATTRIBUTES: {} if NULL (empty map)

  • TYPE: CREDIT_CARD if NULL (typically NULL if the saved payment was created from customer profile)

  • VERSION: 1

  • TRK_TENANT_ID: 'UNKNOWN_TENANT_ID'

    • If any records have 'UNKNOWN_TENANT_ID' as TRK_TENANT_ID, those values should be manually updated to the correct tenant id

Additional Notes

  • TRK_CHANGE_DETAILS is not copied over to the new table

  • The following columns in the old table are copied over to different columns in the new table:

    • PAYMENT_GATEWAY_PROPERTIES > PAYMENT_METHOD_PROPERTIES

    • ACCOUNT_TYPE > TYPE

    • DISPLAY_NAME > NAME

    • DEACTIVATED > TRK_ARCHIVED

Data Migration for New Columns in Payment

The following new columns are introduced to paymenttransaction.blc_payment in this release:

  • should_save_pmt_for_future_use

    • A new flag to replace should_save_pmt_to_customer

  • owning_user_type

    • Indicates the type of user that owns this payment, i.e. BLC_CUSTOMER

  • owning_user_id

    • Indicates the id of user that owns this payment, i.e. customer id

This migration scripts for these new columns are added as liquibase changesets, so no manual step is necessary.

Values Set from Migration Scripts

The following fields have the corresponding values:

  • should_save_pmt_for_future_use is set from should_save_pmt_to_customer

  • If is_customer_registered == 'Y'

    • owning_user_type is set to BLC_CUSTOMER

    • owning_user_id is set to customer_id

  • If is_customer_registered == 'N'

    • owning_user_type is set to ANONYMOUS

    • owning_user_id is set to NULL

Verifying the Migrations

Once the migration scripts have been executed, it’s important to verify that the migrated data looks correct.

Especially keep an eye out for any records that contain TRK_TENANT_ID = 'UNKNOWN_TENANT_ID'. These records indicate that a payment account could not be identified for the saved payment method.

Configuration Properties

Added Properties

  • broadleaf.paymenttransaction.saved-payment-method.storage-location

  • broadleaf.paymenttransaction.saved-payment.checkout-complete-create-listener.enabled

  • broadleaf.paymenttransaction.web.saved-payment-method.legacy-permission-enabled

    • Description: Determines whether the legacy permissions (CUSTOMER and CUSTOMER_PROFILE) should be used for CustomerSavedPaymentMethodManagementEndpoint

      See Legacy Permissions Configuration for more details

  • broadleaf.paymenttransaction.reversal.reversal-candidate-ttl

    • Description: The amount of time the payment transactions with managementState = "REVERSAL_CANDIDATE" can be used, before their reversal is processed.

    • Default value: 15 minutes

  • broadleaf.paymenttransaction.anonymization.enabled

    • Description: Whether or not anonymization is enabled at all

    • Default value: true

  • broadleaf.paymenttransaction.anonymization.payment-enabled

    • Description: Whether or not anonymization specific to the Payment domain is supported

    • Default value: true

  • broadleaf.paymenttransaction.anonymization.payment-method-properties-to-process

    • Description: The list of Payment method property keys whose values should be anonymized

  • broadleaf.paymenttransaction.anonymization.attributes-to-process

    • Description: The list of Payment attribute keys whose values should be anonymized

  • broadleaf.paymenttransaction.anonymization.display-attributes-to-process

    • Description: The list of Payment display attribute keys whose values should be anonymized

  • broadleaf.paymenttransaction.anonymization.transaction-attributes-to-process

    • Description: The list of Payment transaction attribute keys whose values should be anonymized

  • broadleaf.paymenttransaction.webhook.notification.failure-rate-threshold

    • Description: Configures the failure rate threshold in percentage above which the CircuitBreaker should trip open and start short-circuiting calls

    • Default value: 50.0

  • broadleaf.paymenttransaction.webhook.notification.ring-buffer-size-in-closed-state

    • Description: Configures the size of the ring buffer when the CircuitBreaker is closed. The CircuitBreaker stores the success/failure status of the latest calls in a ring buffer

    • Default value: 100

  • broadleaf.paymenttransaction.webhook.notification.ring-buffer-size-in-half-open-state

    • Description: Configures the size of the ring buffer when the CircuitBreaker is half open. The CircuitBreaker stores the success/failure status of the latest calls in a ring buffer

    • Default value: 10

  • broadleaf.paymenttransaction.webhook.notification.wait-duration-in-open-state

    • Description: Configures the wait duration which specifies how long the CircuitBreaker should stay open, before it switches to half open

    • Default value: 60 seconds

  • broadleaf.paymenttransaction.webhook.notification.send-timeout

    • Description: The length of time a message send attempt should block before timing out. Such a timeout is considered a failure

    • Default value: 30 seconds

  • broadleaf.paymenttransaction.webhook.retry.retry-cluster-service-namespace

    • Description: Name used to identify the cluster singleton lock

  • broadleaf.paymenttransaction.webhook.retry.retry-interval

    • Description: The length of time to wait between each batch retry attempt

    • Default value: 5 minutes

  • broadleaf.paymenttransaction.webhook.retry.page-size

    • Description: The number of valid, unacknowledged records to batch process per interval

    • Default value: 1000

  • broadleaf.paymenttransaction.webhook.retry.max-attempts

    • Description: The maximum number of failed attempts that should be made before ceasing to attempt to send a message for an unacknowledged record

    • Default value: 10

  • broadleaf.paymenttransaction.webhook.retry.max-attempt-wait-time

    • Description: The maximum amount of time that should elapse before making another attempt on an unacknowledged record. The time between retries for an individual record is generally governed by a exponential backoff algorithm, but this value represents a ceiling beyond which that algorithm may not exceed

    • Default value: 4 hours

  • broadleaf.paymenttransaction.webhook.retry.initial-fault-threshold

    • Description: The amount of time that must elapse before the retry mechanism can kick in on a newly altered and unacknowledged record. This provides a safe window in which the normal operation can acknowledge the record without risk of interference from the retry handler

    • Default value: 5 minutes

  • broadleaf.paymenttransaction.webhook.retry.record-processing-wait

    • Description: The amount of time to pause between the processing of each unacknowledged record in the batch. This is primarily a throttling measure

    • Default value: 0

  • broadleaf.paymenttransaction.webhook.retry.delay-at-startup

    • Description: The amount of time after initialization of the application that must pass before the retry scheduler starts. Can be used to provide some buffer of time for other components (e.g. kafka bindings) to fully initialize

    • Default value: 20 seconds

Auth Configuration

New Permissions

There are new permissions and scopes for the OAuth2 clients and the customer user role. Permissions and scopes can be added via admin or sql script.

See AuthServices 1.7.2 release notes for more details.