Broadleaf Microservices
  • v1.0.0-latest-prod

Tabby Environment Setup

Adding the Tabby Dependency

Once you have setup account with Tabby, add the Broadleaf Tabby Maven dependency to your PaymentTransactionServices project.

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

Configuring Your Integration

Tabby Configuration

broadleaf:
  tabby:
    public-key: {Public Key}
    secret-key: {Secret Key}
    merchant-code: {Merchant Code} (1)
    webhook-signature: {Webhook Signature} (2)
    read-anonymous-orders-enabled: false (3)
    orderopsprovider:
      url: https://localhost:8447 (4)
      customer-order-info-uri: /order-info (5)
      anonymous-customer-order-info-uri: /anonymous (6)
      max-order-history-size: 10 (7)
      batch-size: 10 (8)

  1. The Merchant code is optional in the configuration and instead can be specified in the paymentMethodProperties when creating Payment in PaymentTransactionServices. The merchant code from the configuration is used only if it is not specified in the paymentMethodProperties.

  2. The webhook signature is used to validate the webhook request that Tabby sends. It must be equal to the value you specified in the header value when registering your webhook endpoint through the Tabby API. See more about the webhook in the section Webhook Configuration below.

  3. If true the buyer and order history of the Tabby payment will be populated for the anonymous customers. Defaults to false.

  4. Required. The buyer and order history of the Tabby payment from paymentMethodProperties will be updated based on the Order history of the authorized customer. See Add Buyer and Order History.

  5. The URI to read the Orders for customers. These orders are used to populate the buyer and order history of the Tabby payment. Defaults to /order-info.

  6. The URI to read the Orders for anonymous customers. This is only used if broadleaf.tabby.read-anonymous-orders-enabled is true. Defaults to /anonymous.

  7. The maximum number of orders to read. Allowed minimum value is 1 and maximum value is 100. Defaults to 10.

  8. The maximum number of orders to read per batch. Allowed minimum value is 1 and maximum value is 50. Defaults to 10.

Cart Operation Configuration

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

broadleaf:
  cartoperation:
    mapping:
      cartitem:
        product-mappings:
          - attributeName: 'categoryNames' (1)
            valuePath: '$.parentCategories[*].name'
    service:
      checkout:
        external-payment-transaction:
          callback-redirection:
            storefrontBaseUrl: https://{storefrontUrl} (2)
            default-redirect-uri: /checkout/payment-confirmation (2)
        checkout-transaction-types:
          TABBY: AUTHORIZE
        checkout-lookup-external-transactions-enabled:
          TABBY: true
        checkout-payment-method-options:
          - payment-method-type: BNPL
            payment-method-gateway-type: TABBY

  1. The Tabby requires to specify the category name for the order items. By specifying this attribute mapping you will be able to get the category name from the cart.cartItem.attributes?.categoryNames. It is possible that there is more than 1 category, in this case, get the first one from the categoryNames attribute.

  2. This configuration is required if the new improved 3DS/HPP pattern is used. See Improved 3DS/HPP pattern integration example for more information.

Order Operation Service Configuration

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

broadleaf:
  orderoperation:
    service:
      payment:
        enable-auto-capture: true (1)
        auto-capture-payment-gateways:
          - TABBY (2)

  1. If true, auto-capture will be enabled for the specified

    • gateways from broadleaf.orderoperation.service.payment.auto-capture-payment-gateways during order creation.

  2. The gateway name to automatically capture the payment during order creation. Tabby doesn’t support AUTHORIZE_AND_CAPTURE transactions, but it is recommended to capture the payment after it is successfully authorized.

Authentication Service Data Configuration

To access the endpoint to initial PreScoring step, the following permissions must be defined:

Initiate PreScoring Permissions 
INSERT INTO auth.blc_security_scope ("id", "name", "open") VALUES ('-630', 'TABBY_PRE_SCORING', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id) VALUES('-1030', 'TABBY_PRE_SCORING', 'Y', '-630');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id) VALUES('-1031', 'TABBY_PRE_SCORING', 'Y', '-100');

-- Add permission to customer role
INSERT INTO auth.blc_user_permission ("id", "archived", "last_updated", "name", "is_account_perm") VALUES('-1030', 'N', '1970-01-01 00:00:00.000', 'ALL_TABBY_PRE_SCORING', 'N');
INSERT INTO auth.blc_role_permission_xref (role_id, permission_id) VALUES ('-100', '-1030');

-- Add permission to anonymous client (used for anonymous customers)
INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('anonymous', 'TABBY_PRE_SCORING');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('anonymous', 'ALL_TABBY_PRE_SCORING');

-- Add permission to OpenAPI
INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('openapi', 'TABBY_PRE_SCORING');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('openapi', 'ALL_TABBY_PRE_SCORING');

To grant PaymentTransactionServices access to gather the customer’s order history for the payment, the following permissions must be defined:

Gather Customer Order History Permissions 
INSERT INTO auth.blc_security_scope ("id", "name", "open") VALUES ('-638', 'CUSTOMER_ORDER_INFO', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id) VALUES('-1038', 'CUSTOMER_ORDER_INFO', 'Y', '-638');
INSERT INTO auth.blc_security_scope ("id", "name", "open") VALUES ('-639', 'ANONYMOUS_CUSTOMER_ORDER_INFO', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id) VALUES('-1039', 'ANONYMOUS_CUSTOMER_ORDER_INFO', 'Y', '-639');

-- Add permissions to paymenttransaction client (used by PaymentTransactionServices)
INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('paymenttransactionclient', 'CUSTOMER_ORDER_INFO');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('paymenttransactionclient', 'READ_CUSTOMER_ORDER_INFO');
INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('paymenttransactionclient', 'ANONYMOUS_CUSTOMER_ORDER_INFO');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('paymenttransactionclient', 'READ_ANONYMOUS_CUSTOMER_ORDER_INFO');

-- Add permissions to OpenAPI client
INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('openapi', 'CUSTOMER_ORDER_INFO');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('openapi', 'READ_CUSTOMER_ORDER_INFO');
INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('openapi', 'ANONYMOUS_CUSTOMER_ORDER_INFO');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('openapi', 'READ_ANONYMOUS_CUSTOMER_ORDER_INFO');

To access the endpoint to check the transaction result add following permissions:

External Transaction Result Endpoint Permissions 
-- EXTERNAL_TRANSACTION_RESULT
INSERT INTO auth.blc_security_scope (id, "name", "open") VALUES('-1800', 'EXTERNAL_TRANSACTION_RESULT', 'N');

INSERT INTO auth.blc_permission_scope(id, permission, is_permission_root, scope_id) VALUES('-1800', 'EXTERNAL_TRANSACTION_RESULT', 'Y', '-1800');
INSERT INTO auth.blc_permission_scope(id, permission, is_permission_root, scope_id) VALUES('-920', 'EXTERNAL_TRANSACTION_RESULT', 'Y', '-100');

INSERT INTO auth.blc_user_permission(id, archived, last_updated, "name") VALUES('-1100', 'N', '1970-01-01 00:00:00.000', 'ALL_EXTERNAL_TRANSACTION_RESULT');

INSERT INTO auth.blc_client_scopes(id, "scope") VALUES('anonymous', 'EXTERNAL_TRANSACTION_RESULT');
INSERT INTO auth.blc_client_scopes(id, "scope") VALUES('cartopsclient', 'EXTERNAL_TRANSACTION_RESULT');

INSERT INTO auth.blc_client_permissions(id, permission) VALUES('anonymous', 'ALL_EXTERNAL_TRANSACTION_RESULT');
INSERT INTO auth.blc_client_permissions(id, permission) VALUES('cartopsclient', 'ALL_EXTERNAL_TRANSACTION_RESULT');

INSERT INTO auth.blc_role_permission_xref (role_id, permission_id) VALUES ('-100', '-1100');

-- Add permission to OpenAPI
INSERT INTO auth.blc_client_scopes (id, scope) VALUES ('openapi', 'EXTERNAL_TRANSACTION_RESULT');
INSERT INTO auth.blc_client_permissions (id, permission) VALUES ('openapi', 'ALL_EXTERNAL_TRANSACTION_RESULT');
Note
 Based on the Auth data configured in your environment, you may need modify the ids defined in the scripts above.

Webhook Configuration

To register the webhook endpoint use the Register a webhook API.

The example of the webhook request body:

curl --location 'https://api.tabby.ai/api/v1/webhooks' \
--header 'X-Merchant-Code: {merchant_code}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {secret_key}' \
--data '{
    "url": "https://{host}/api/payment/webhooks/TABBY?applicationId=2&tenantId=5DF1363059675161A85F576D",
    "is_test": true, (1)
    "header": {
        "title": "X-Webhook-Signature", (2)
        "value": "test" (3)
    }
}'

  1. Indicates whether to use this hook in test environment or not.

  2. The signature header name

  3. Random secret string to sign the request. It should be equal to the value specified in broadleaf.tabby.webhook-signature

Local Webhook Configuration using Ngrok

localhost is not an allowed domain for Tabby webhooks. To correctly direct webhook requests from Tabby to your local instance, we suggest using Ngrok.

The following steps describe how to configure Ngrok in your local environment:

  1. Execute ngrok http https://{yourAppUri}/ to build the tunnel to your local app. Replace yourAppUri with your app URI e.g. myapp.localhost:8446

Configure Tabby API endpoints

The following configuration defines the default API URLs to execute the requests to the Tabby API

broadleaf:
  tabby:
    provider:
      api-url: https://api.tabby.ai/api
      create-checkout-session-uri: /v2/checkout
      retrieve-payment-uri: /v2/payments/{id}
      capture-payment-uri: /v1/payments/{id}/captures
      refund-payment-uri: /v1/payments/{id}/refunds
      close-payment-uri: /v1/payments/{id}/close