Stripe Dispute Webhook - Overviews

Stripe Dispute Webhook

How to provide Forter access to your Stripe Dispute Webhooks. To enable Forter to process your chargebacks, please integrate your PSP with Forter by following these steps.

Required Keys Required Keys

  1. API Key - Secret

  2. Webhook

Include Stripe ID value in payment auth details
A unique identifier is generated by Stripe during payment authorization that differs from your orderId. This is required to map the dispute back to the original transaction. Map Stripe's PaymentIntent ID (the value that starts with pi_) to the processorTransactionId field in your Order API or Order Status API request, when you send Forter the payment authorization details. The Charge ID (ch_) is also supported as a legacy alternative.

Partial code example

{
  "creditCard": {
    "nameOnCard": "John Smith",
    "bin": "424242",
    "lastFourDigits": "4242",
    "countryOfIssuance": "US",
    "expirationMonth": "03",
    "expirationYear": "2025",
    "verificationResults": {
      "authorizationCode": "A33244",
      "avsFullResult": "Y",
      "processorResponseCode": "188502",
      "processorResponseText": "Authorised"
    },
    "cardBrand": "VISA",
    "paymentProcessorData": {
      "processorTransactionId": "pi_3M7nAB2ck0FfgL3IAbc1DEfG",
      // PaymentIntent ID assigned by Stripe (recommended)
      "processorName": "Stripe"
    },
    "fullResponsePayload": {}
  }
}

Alternatively, you can include the fullResponsePayload object with the id key.

Partial code example

{
  "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": {}
  }
}
  1. Go to the Developers Tab

Log into your Stripe Admin account and go to the Developers tab.

  1. Generate an API key and share with Forter

Under "Restricted keys", click +Create restricted key.
Typically, the key that is generated will start with rk_live or sk_live for your production environment.

Set the following permissions:

  1. Charges → Read
  2. Customers → Read
  3. Files → Write
  4. PaymentIntents → Read
  5. PaymentMethods → Read
  6. Invoices → Read
  7. Subscriptions → Read
  8. Disputes → Write (under All core resources

Save the API Key - Secret key to a .txt file with the file naming convention "JCBR-yourSiteName-processorName" (e.g. "JCBR-TShirtsExpress-Stripe"). Keep this .txt file open as you will add the webhook keys to it in the next steps.

  1. Configure a New Webhook

Navigate to the Webhooks section and select Add Endpoint
Add a new webhook endpoint with the following url https://api.forter-secure.com/webhooks/stripe/`` using the site ID from the Credentials section of Forter Portal.
Check all events under charge.dispute.

  1. Copy the Webhook Signing Secret
    After saving, click on your newly created webhook destination. Reveal and copy the Signing secret (starts with whsec_...).
    Save the signing secret to a .txt file that you had in step 3 "JCBR-yourSiteName-processorName" (e.g. "JCBR-TShirtsExpress-Stripe") and upload it securely to your S3 folder. Please notify your Forter Implementation Engineer once you have uploaded these files. Your Forter Implementation Engineer will securely add your secret key to the Forter database and let you know when this step is complete.

  2. Test the endpoint
    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.

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.