> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Dispute notifications

> Understand dispute notification payloads and when each event is sent.

The important fields in the dispute notification include:

* event is`executionActionCompleted`
* action is`dispute`
* there's a `dispute` block in the `paymentComposition`object
  * `dispute.amount` shows the disputed amount
  * both `dispute.id` and `dispute.providerReference` show the dispute reference given by the PSP
  * `dispute.paymentId` shows the original ID of the payment to which the dispute has been filed
  * `dispute.reason` is a reason of the dispute coming from the PSP
  * `dispute.status` is a Payrails dispute status, mapped from the PSP status.

`dispute.status` in the Dispute notification can be one of the following:

| dispute.status | Description |
| :- | :- |
| `FraudAlert` | Just a flag, no actions required. |
| `RetrievalOpened` | Claim motion filed on the issuer side, action is required before this is chargeback. |
| `RetrievalChallenged` | Merchant filed defense to the claim. |
| `RetrievalExpired` | Merchant took no action in the grace period. |
| `DisputeNotified` | Chargeback is about to be issued. |
| `DisputeOpened` | Chargeback took place already. |
| `DisputeChallenged` | Merchant defended their position on the chargeback. |
| `DisputeWon` | Issuer accepted Merchant defense. |
| `DisputeLost` | Issuer rejected Merchant defense. |
| `DisputeExpired` | Merchant took no action in the grace period. |
| `DisputeAccepted` | Merchant accepted the user's dispute and decided not to challenge. |
| `DisputeCancelled` | User cancelled their dispute. |
| `ArbitrationOpened` | (available only in selected schemes) Merchant requested 2nd arbitration. |
| `ArbitrationWon` | Merchant won the arbitration. |
| `ArbitrationLost` | Merchant lost the arbitration |

Currently supported PSPs are: Adyen, Stripe, checkout.com, dLocal.

**A notification example:**

Some of the details of the objects that are not relevant to the Dispute are omitted in this example (like `customer`, `order`, or `risk`).

```json Dispute notification theme={null}
{
  "action": "dispute",
  "actionId": "11111111-2e6e-5499-9bba-8795e382da46",
  "amount": {
    "currency": "USD",
    "value": "10.00"
  },
  "execution": {
    "holderId": "",
    "holderReference": "",
    "id": "",
    "merchantReference": "",
    "meta": {
      "clientContext": {},
      "customer": {},

      "order": {},
      "risk": {},
      "vendor": {}
    },

    "providerReference": "ref_111122223333",
    "workflowCode": "payment-acceptance"
  },
  "paymentComposition": [
    {
      "acquirerMID": "112233", // if sent by provider
      "authorizationCode": "445566", // if sent by provider
      "acquirerAccountCode": "value", // if sent by provider
      "acquirerReference": "1122334455", // if sent by provider

      "amount": {
        "currency": "USD",
        "value": "10.00"
      },
      "dispute": {
        "amount": {
          "currency": "USD",
          "value": "10.00"
        },
        "createdAt": "2025-11-18T17:48:31Z",
        "id": "dispute_ref_111122223333",
        "network": "",
        "paymentId": "payment_111122223333",
        "providerReference": "dispute_ref_111122223333",
        "reason": "unauthorized_use_of_card",
        "status": "FraudAlert"
      },

      "integrationType": "api",

      "operationProviderReference": "dispute_ref_111122223333",

      "operationResult": "Success",

      "operationType": "ChargebackNotification",

      "paymentId": "payment_111122223333",

      "paymentInstrument": {
        "createdAt": "2025-10-10T10:56:16.342222Z",
        "data": {
          "bin": "411111",
          "binLookup": {
            "bin": "411111",
            "issuer": "BANK OF AMERICA",
            "issuerCountry": {
              "code": "US",
              "iso3": "USA",
              "name": "UNITED STATES"
            },
            "network": "visa",
            "segment": "classic",
            "type": "DEBIT"
          },
          "expiryMonth": "03",
          "expiryYear": "2027",
          "network": "visa",
          "networkDisplayName": "Visa",
          "suffix": "1111"
        },
        "default": false,
        "description": "Payment instrument for user",
        "displayName": "Visa **** 1111",
        "fingerprint": "",
        "holderId": "",
        "id": "",
        "merchantReference": "",
        "paymentMethod": "card",
        "status": "transient",
        "updatedAt": ""
      },

      "paymentInstrumentId": "",

      "paymentInstrumentToken": {
        "meta": {
          "holderReference": ""
        },
        "reference": "",
        "type": "vault"
      },

      "paymentInstrumentTokenId": "",
      "paymentMethodCode": "card",
      "provider": {
        "configSchema": "",
        "createdAt": "",
        "displayName": "Stripe",
        "id": "",
        "name": "stripe",
        "notificationURLTemplate": "",
        "status": "active",
        "type": "Payment",
        "updatedAt": ""
      },
      "providerConfigId": "",
      "providerId": "",
      "providerReference": "ref_111122223333",
      "retries": {},
      "storeInstrument": false,
      "success": true,
      "threeDS": {
        "authenticationType": "",
        "authenticationValue": "",
        "dsTransId": "",
        "eci": "",
        "transStatus": "",
        "transStatusReason": "",
        "version": "2.2.0"
      }
    }
  ],
  "success": true
}
```


## Related topics

- [Get Dispute Activities by Dispute ID](/reference/getdisputeactivities.md)
- [Notifications](/docs/resources/notifications/index.md)
- [Klarna](/docs/chargebacks/integrations/klarna.md)