Broadleaf Microservices
  • v1.0.0-latest-prod

Stripe ACH Environment Setup

Prerequisites

Prior to configuring your environment for Stripe ACH, please complete the base environment setup guide.

Stripe Configuration

In the Stripe Dashboard, you’ll need to enable the ACH payment method.

Configuring your Stripe Webhooks

As part of the Stripe 3DS solution, we use webhooks to ensure that transaction results are known by the Broadleaf ecosystem.

In the Stripe Dashboard, declare the webhook url using the following structure to hit the PaymentTransactionServices webhook endpoint: https://${host}/api/payment/webhooks/STRIPE

Note
 Make sure to replace ${host} with the value relevant to your environment

To ensure the validity of inbound requests, we confirm that the request’s signature matches the value that we calculate using a secret key provided by Stripe. To define this key in your Broadleaf ecosystem, the following property must be declared:

broadleaf:
  stripe:
    rest:
      webhook-endpoint-secret: {Your webhook endpoint secret}
Note

If your solution requires different Stripe accounts per tenant or per application, then you’ll want to leverage the ability to provide application-discriminated and/or tenant-discriminated values for the webhook secret.

For example:

  • broadleaf.stripe.rest.tenant.mytenant.webhook-endpoint-secret=…​

  • broadleaf.stripe.rest.application.myapplication.webhook-endpoint-secret=…​

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

To correctly identify & engage these application-discriminated and/or tenant-discriminated webhook secrets, you’ll need to pass the relevant application and/or tenant ids as parameters via the webhook requests. This should be done by defining the webhook url using the following parameters: https://${host}/api/payment/webhooks/STRIPE?applicationId=myapplication&tenantId=mytenant

Cart Operation Service Configuration for ACH Payments

Add the following properties to declare the STRIPE gateway & ACH payment method as an available payment method.

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-payment-method-options:
          - payment-method-type: ACH
            payment-method-gateway-type: STRIPE

Stripe ACH payments always use AuthorizeAndCapture transactions. To ensure that CartOperationServices only attempts AuthorizeAndCapture transactions for ACH, the following property must be declared:

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-transaction-types:
          STRIPE.ACH: AUTHORIZE_AND_CAPTURE

Order Operation Service Configuration for ACH Payments

When the order is canceled or an order item is returned, the refund transaction is executed and this transaction requires the async result from the webhook. When the refund transaction is completed Stripe sends the webhook event to the webhook endpoint. After this event is processed successfully, the webhook sends an event to the paymentTransactionWebhookOutput message channel. This event should be processed by the FulfillmentAwaitingRefundResultWebhookListener or ReturnConfirmationRefundWebhookListener listeners in the OrderOperationService. By default, these listeners are disabled. To enable them add the following property:

broadleaf:
  orderoperation:
    async-payment-transaction-support:
      enabled: true

Authentication Service Data Configuration

The following permissions must be defined for Stripe ACH:

Stripe Payment Intent endpoint Permissions 
INSERT INTO auth.blc_security_scope ("id", "name", "open") VALUES ('-611', 'STRIPE_PAYMENT_INTENT', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id) VALUES('-1011', 'STRIPE_PAYMENT_INTENT', 'Y', '-611');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id) VALUES('-1012', 'STRIPE_PAYMENT_INTENT', 'Y', '-100');

INSERT INTO auth.blc_user_permission ("id", "archived", "last_updated", "name", "is_account_perm") VALUES('-1011', 'N', '1970-01-01 00:00:00.000', 'ALL_STRIPE_PAYMENT_INTENT', 'N');
INSERT INTO auth.blc_role_permission_xref (role_id, permission_id) VALUES ('-100', '-1011');

INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('anonymous', 'STRIPE_PAYMENT_INTENT');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('anonymous', 'ALL_STRIPE_PAYMENT_INTENT');

INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('openapi', 'STRIPE_PAYMENT_INTENT');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('openapi', 'ALL_STRIPE_PAYMENT_INTENT');
Note
 Based on the Auth data configured in your environment, you may need modify the ids defined in the scripts above.

Local Testing

Stripe ACH transaction results are always communicated via webhook interactions. To get the webhooks setup up for local testing, see Stripe’s local testing guide.

Along with this, you’ll need to declare the webhook endpoint secret key for your test environment.

broadleaf:
  stripe:
    rest:
      webhook-endpoint-secret: {Your webhook endpoint secret}

Once your local Broadleaf app is up and running with the Stripe module & all relevant configuration, the following Stripe CLI command should be used to start listening for webhook events:

stripe listen --skip-verify --forward-to https://localhost:8447/webhooks/STRIPE

Going to Production

  1. Make sure that you’ve finished enabling ACH payments with the Stripe Dashboard.

  2. Make sure that you’ve defined your production webhooks & provided your webhook endpoint secret to the Broadleaf ecosystem