Configure Braintree for ACH Payments

Braintree supports handling Automated Clearing House (ACH) payments and refunds using the Braintree Payment Gateway Adapter.

About this task

ACH is a direct debit method where the customer grants the merchant permission to collect funds from their bank account. ACH payments are subject to a three-day cycle, which means they are suitable only for Auto Recharge scenarios where the payment request can be made three days in advance of the recharge date.

Braintree communicates success or decline at the end of the three-day payment cycle using webhooks. In the event of a decline, MATRIXX voids the payment automatically.

Note: For ACH payments to work using Braintree, ingress must be configured using secure TLS/SSL with CA. The payment gateway does not accept self-signed certificates. For information about configuring ingress for ACH payments, contact your MATRIXX Support representative.
Before you configure the Braintree webhook, add userDefinedFields in the payment service .yaml or .properties file. You must also include the ChargeMethodAttr in the purchase offer to pass in LLASubscriptionExteralId as a custom field. 
{
    "$": "MtxRequestSubscriberPurchaseOffer",
    "ChargeMethodData":
    {
    "$": "MtxChargeMethodData",
    "ChargeMethod": 2,
    "PaymentGatewayId": 0,
    "ChargeMethodAttr":
    {
        "$": "LLABraintreeChargeMethodExtension",
        "LLASubscriptionExternalId": "MTX1687327657564"
    }
    },
   "OfferRequestArray": [
    {
      "$": "MtxPurchasedOfferData",
      "CatalogItemId": "20",
      "ParameterArray": [
        {
          "$": "MtxParameterData",
          "ParameterName": "RecurringCharge 01",
          "Value": {
            "$": "MtxParameterDecimalValue",
            "Value": 44444.44
          }
        }
      ]
    }
  ]
}

To support ACH payments using Braintree for Pay Now, you must define the following webhook configuration for Braintree.

Procedure

  1. Set the webhook as POST {paymentServicePrefixURL}/payment/webhook/configName/{configName}.
    For example:
    paymentServicePrefixURL = https://testpayment.matrixx-engineering.com
configName = default
  2. Configure the above webhook URL in the Braintree Control Panel.
  3. Configure the Payment Service. The configuration should look similar to the following where configName = default: 
    payment:
  gateway:
    braintree:
      configs:
        default:
          environment: sandbox
          merchantId: sw994qcnv99xw42b
          publicKey: d4kj2kry84qj7gpf
          privateKey: bf95fbbe9f6696c93d22e7b28bb34dbb
          recurringOverrideFieldName: RecurringIndicator
          retryOperations : [ 1, 2, 7 ]
          transactionErrors: { 3: [ 2034, 4002 ], 4: [ 2001, 4006 ] }
          # 10 timeout, 8 Server
          transportErrors: [ 10 ]
          # If true the partial refunds are only attempted if the transaction has settled
          partialRefund: true
          userDefinedFields:
            llasubscriptionexternalid:
              mdcFieldName: LLASubscriptionExternalId
              defaultValue: NA
              systemInitiatedValue: NA
  4. If the ACH settlement is declined, the decline reason information is available from Braintree in the corresponding events so you can identify and distinguish between a refund and a void:
    • The decline reason details from Braintree include a Reason field — MtxRefundEvent > "Reason": "Webhook ACH Settlement decline:R01:SETTLEMENT_DECLINED"
    • MATRIXX Engine includes the decline reason from Braintree in the PaymentGatewayOpDescription — MtxPaymentRefundEvent > "PaymentGatewayOpDescription": "REFU:44444.44:Webhook ACH Settlement decline:R01:SETTLEMENT_DECLINED"