Integration Guides

Stripe Disputes Webhook

This guide details a few simple configurations needed in your Stripe account to enable Forter to receive automatic notification of chargebacks via webhooks. This streamlines the process of chargeback updates. It ensures that Forter’s real-time decisions are based on the latest data, contributing to the system’s accuracy, and prevents unnecessary delays in the reimbursement of chargebacks covered by Forter’s Chargeback Guarantee.

Suggest Edits

Pre-Step: Mapping the Stripe ID in your Validation API
In order to make sure the chargeback is matched with the correct order, please verify the Stripe Charge Object ID (the value that starts with ch_ ) which is generated when the order authorization, is sent to Forter via the Order Validation API in one of the following objects:

Within the payment details, as the gatewayTransactionId property in the PaymentGatewayData object.

 "payment":[
  {
    "creditCard": {
      "nameOnCard": "Aner Barniv",
      "bin": "442666",
      "lastFourDigits": "3219",
      "expirationMonth": "07",
      "expirationYear": "2022",
      "verificationResults": {},
      "paymentGatewayData": {
        "gatewayName": "Stripe",
        "gatewayTransactionId": "ch_1EV3DH2ck0FfgL3IXy4CUTMW" // Stripe Charge object
      }
    }
  }
]

In the Order Validation API request object, as an id key in the fullResponsePayload Object.

"fullResponsePayload": {
    "id": "ch_1EV3DH2ck0FfgL3IXy4CUTMW",
    "object": "charge",
    "amount": 2295, 
    "amount_refunded": 0,
    "application": null,
    "application_fee": null,
    "application_fee_amount": null,
    "balance_transaction": "txn_1EV3DI2ck0FfgL3IIRzYHb40",
    "billing_details" {}
}

Step 1: Go to the Developers Tab
Log into your Stripe Admin account and go to the Developers tab

Step 2: Generate an API key
Generate a Secret Key that will be used by Forter to authenticate the source of the data. This key should have Write permissions for (1) Disputes (2) Files resources. Typically, the key that is generated will start with rk_live or sk_live for your production environment.

To generate this key, click on the “API Keys” section under the Developers tab and go to the Restricted Keys section.

Send the access credentials to Forter via secure S3 bucket transfer. 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-Stripe") and upload it to your secure Forter S3. Instructions for accessing your S3 can be found at the bottom of the Historical Data Transfer Page. Please notify your Forter Project manager once these credentials have been uploaded.

Step 3: Configure a New Webhook
Go to Developers > Webhooks on your dashboard

Step 4: Add an Endpoint
Go to the webhooks section and select Add Endpoint

Add a new webhook endpoint with the following url https://api.forter-secure.com/webhooks/stripe/

Your Forter site id can be found in the API Reference section of the Forter portal. Select all events starting in charge.dispute

After your Forter team has encrypted and added your Stripe Secret key to the Forter database, please test the endpoint url to confirm a 200/success response from the Forter server.

Step 5: Test the endpoint
If you're able to set up a sandbox Stripe webhook for your Forter sandbox environment, you can reference Stripe's list of test cards and procedure to generate a dispute in their sandbox. Please place an order with one of their test cards to test a dispute in sandbox.

As always, we value your feedback. If you have any questions or comments, please reach out to [email protected] .

Updated 3 days ago