Braintree Disputes Webhook

Pre-Step: Map the Braintree id to the relevant API field
In order to connect the original Transaction to a chargeback in Forter's system, the relevant Braintree unique transaction identifier will need to be exposed in the Validation API. This identifier is generated by the Braintree gateway and will typically be a 6 - 10 digit alphanumeric string that differs from the merchant-generated OrderId. Please map this value to the gatewayTransactionId field in the Validation API.

 "payment": [
    {
      "billingDetails": {},
      "creditCard": {
        "nameOnCard": "Jane Smith",
        "bin": "442757",
        "lastFourDigits": "5149",
        "expirationMonth": "11",
        "expirationYear": "2024",
        "verificationResults": {},
        "cardType": "DEBIT",
        "countryOfIssuance": "USA",
        "paymentGatewayData": {
          "gatewayName": "Braintree",
          "gatewayTransactionId": "gk1m4r2j" // Braintree transaction.id
        }
      }
    }
  ]

Step 1: Generate API Key
After logging into your Braintree account, click on the small "gear" icon on the upper right-hand corner and select "API" from the menu.

2. In the Keys tab of the API page, click on the Generate New API Key button to generate a new set of keys including:
   Private Key
   Public Key
   Merchant ID
3. Once you've generated keys, copy and paste the Private Key, Public Key, Merchant ID values into a .txt file.
4. Ensure the credentials are saved under the file naming convention "JCBR-merchantName-processorName" where processorName is a placeholder for which processor these keys are for (ex. "JCBR-merchantName-Braintree") and upload this file to your secure S3.
5. A direct link to your secure S3 bucket can be found at the bottom of Historical Data Upload Page
6. After you've uploaded the .txt file to your S3, inform your Forter onboarding team who will then encrypt the Braintree keys you provided and add them to the Forter database to authenticate webhook calls from your Braintree account.

Step 2: Create a Webhook Endpoint
After uploading your API keys to your S3, click on the Webhooks tab in your API settings and click on the Create New Webhook Button.

Add a new webhook endpoint with the following URL: https://api.forter-secure.com/webhooks/braintree/
Your Forter Site Id can be found in the API Reference section of the Forter portal.

Please make sure to add the siteId that corresponds to the Braintree environment you're adding the webhook to (i.e. production Forter site Id for Production Braintree webhook, sandbox site Id for sandbox Braintree webhook)

Select the following options under the "Disputes" section:
Lost
Open
Won
Accepted
Disputed
Expired

Test the endpoint Once Forter has confirmed that your API keys from Step 1 have been added to the Forter Database, return to the Webhooks section of your braintree admin and click on the "Check URL" option next to your webhook.
You should receive a 200/success response from the Forter endpoint. If you receive a 4XX response, please take a screenshot of your webhook settings (including url being used) and let your onboarding team know so that they can provide further troubleshooting instructions.

All set!
As always, we value your feedback. If you have any questions or comments, please reach out to your dedicated Forter CSM or [email protected].
IMPORTANT - PayPal & Braintree
If you use Braintree to process PayPal transactions, please take the following additional steps to ensure we receive your PayPal chargebacks through Braintree.

Click on the (Gear) icon in the top right corner of the Control Panel.
Click Processing from the drop-down menu
Scroll to the Payment Methods section
Next to PayPal, click the Options link
Check the box next to Manage PayPal Disputes in the Braintree Control Panel
Click Edit next to each linked PayPal account and check the box next to Manage PayPal Disputes in the Braintree Control Panel setting.
Please enable this setting for each relevant PayPal account. To learn more, please see this Braintree support article on PayPal disputes.