> ## 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. # Disputes report > Details on all customer-disputed transactions, including chargeback status, reason codes, and the linked original transaction. export const DownloadDisputesCSV = ({filename = "sample-disputes-report.csv"}) => { const handleDownload = () => { const data = `CREATED_AT,DEFENSE_PERIOD_EXPIRES_AT,DEFENSE_STATUS,PROVIDER_REFERENCE,AMOUNT,CURRENCY,PROVIDER_NAME,ISSUER_NAME,PAYMENT_METHOD,REASON_CODE,REASON_DESCRIPTION,ASSIGNED_USER_ID,ORIG_TRANSACTION_ID,ORIG_TRANSACTION_DATE,ORIG_TRANSACTION_AMT,ORIG_TRANSACTION_CURR,WORKSPACE_ID,MERCHANT_ID,DISPUTE_ID,MERCHANT_REFERENCE,CHARGEBACK_TYPE,CHARGEBACK_STATUS,SCHEME_REASON_CODE,LIABILITY_SHIFTED,BIN,ISSUER_COUNTRY_CODE,SHOPPER_COUNTRY_CODE,ARN 2026-04-03 14:22:11.668,2026-04-17 23:59:59.000,UnderReview,du_a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d,54.990000000000,EUR,adyen,DEMO FEDERAL CU,card,10.4,fraudulent,,d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a,2026-03-20 09:12:03.552,54.990000000000,EUR,e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8,DEMO,a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d,int_01demo0000000001,Chargeback,Incoming,,TRUE,411111,NL,NL, 2026-04-05 08:03:41.210,2026-04-19 23:59:59.000,Won,du_b2c3d4e5f6a74b8c9d0e1f2a3b4c5d6e,129.500000000000,USD,checkout,REGIONAL CU,card,4853,product_unacceptable,usr_demo_001,e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b,2026-03-22 17:45:09.113,129.500000000000,USD,e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8,DEMO,b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e,int_01demo0000000002,Chargeback,Reversed,,,545678,US,US,74123456789012345678901 2026-04-08 11:15:27.884,2026-04-22 23:59:59.000,Lost,du_c3d4e5f6a7b84c9d0e1f2a3b4c5d6e7f,19.990000000000,GBP,checkout,COASTAL BANK,applePay,4837,fraudulent,,f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c,2026-03-25 06:30:15.001,19.990000000000,GBP,e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8,DEMO,c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f,int_01demo0000000003,Chargeback,Executed,,,601234,GB,GB, 2026-04-10 19:02:58.442,2026-04-25 23:59:59.000,Undefended,du_d4e5f6a7b8c94d0e1f2a3b4c5d6e7f8a,75.000000000000,EUR,adyen,,,13.1,not_received,,,,,,e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8,DEMO,d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a,,Retrieval,,,,,,, 2026-04-12 03:44:19.997,2026-04-27 23:59:59.000,NotDefendable,du_e5f6a7b8c9d04e1f2a3b4c5d6e7f8a9b,32.400000000000,USD,checkout,,,4855,product_not_received,,,,,,e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8,DEMO,e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b,,FraudReport,,,,,,, 2026-04-15 22:40:05.128,2026-04-30 23:59:59.000,Resolved,du_f6a7b8c9d0e14f2a3b4c5d6e7f8a9b0c,64.250000000000,EUR,adyen,DEMO BANK EU,card,10.4,fraudulent,,a2b3c4d5-e6f7-4a8b-9c0d-1e2f3a4b5c6d,2026-03-28 12:05:44.221,64.250000000000,EUR,e1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8,DEMO,f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c,int_01demo0000000004,Retrieval,,,,,DE,DE,`; const blob = new Blob([data], { type: "text/csv;charset=utf-8;" }); const url = URL.createObjectURL(blob); const a = document.createElement("a"); a.href = url; a.download = filename; a.click(); URL.revokeObjectURL(url); }; return Download sample report ; }; The Disputes report only returns data for merchants with the Chargebacks (disputes) module enabled. If the module isn't enabled, the report still generates successfully but is empty. ## Rows fall into two categories * **Payrails-orchestrated disputes** — the original payment was processed through Payrails. These rows have `ORIG_TRANSACTION_ID`, `ORIG_TRANSACTION_DATE`, `ORIG_TRANSACTION_AMT`, `ORIG_TRANSACTION_CURR`, `PAYMENT_METHOD`, `ISSUER_NAME`, `BIN`, and `ISSUER_COUNTRY_CODE` populated. * **External disputes** — raised directly at the PSP, outside Payrails orchestration. The fields above are blank, since that information isn't available in the dispute event. ## Sample report (CSV file). ## Columns | Column | Type | Description | | - | - | - | | CREATED\_AT | TIMESTAMP | Dispute creation timestamp. | | DEFENSE\_PERIOD\_EXPIRES\_AT | TIMESTAMP | Final deadline by which the dispute must be responded to or defended. | | DEFENSE\_STATUS | STRING | Most recent defense status. One of: `NotDefendable`, `Undefended`, `ReadyToSubmit`, `Submitted`, `UnderReview`, `Won`, `Lost`, `Accepted`, `Resolved`, `Unknown`. | | PROVIDER\_REFERENCE | STRING | The payment provider's unique identifier for this dispute record. | | AMOUNT | NUMERIC | Disputed amount, in the dispute currency. | | CURRENCY | STRING | Currency of the disputed amount (e.g. `EUR`, `USD`, `GBP`). | | PROVIDER\_NAME | STRING | Payment provider (PSP) handling the dispute, per your provider configuration (e.g. `stripedispute`). | | ISSUER\_NAME | STRING | Name of the card-issuing bank, from the BIN lookup on the original payment's instrument. Blank for external disputes or non-card payments. | | PAYMENT\_METHOD | STRING | Payment method used on the original transaction (e.g. `card`, `applePay`). Blank for external disputes. | | REASON\_CODE | STRING | Reason code assigned by the issuing bank, per payment network rules (e.g. `10.4`, `4853`). | | REASON\_DESCRIPTION | STRING | Human-readable description of the dispute reason. | | ASSIGNED\_USER\_ID | STRING | ID of the internal operator assigned to handle this dispute. | | ORIG\_TRANSACTION\_ID | UUID | Payrails payment ID of the original disputed transaction. Blank for external disputes. | | ORIG\_TRANSACTION\_DATE | TIMESTAMP | Creation timestamp of the original payment. Blank for external disputes. | | ORIG\_TRANSACTION\_AMT | NUMERIC | Amount of the original payment, in its processing currency. Blank for external disputes. | | ORIG\_TRANSACTION\_CURR | STRING | Processing currency of the original payment. Blank for external disputes. | | WORKSPACE\_ID | UUID | Workspace identifier. | | MERCHANT\_ID | STRING | Merchant identifier. | | DISPUTE\_ID | UUID | Payrails' internal identifier for the dispute. | | MERCHANT\_REFERENCE | STRING | Your own reference for the payment, from the dispute event or, if absent, the original payment. | | CHARGEBACK\_TYPE | STRING | Dispute stage as reported by the provider. One of: `Created`, `FraudReport`, `Retrieval`, `Chargeback`, `PreArbitration`, `Arbitration`, `Unknown`. | | CHARGEBACK\_STATUS | STRING | Chargeback status as reported by the provider. One of: `Incoming`, `Executed`, `Reversed`, `SecondChargeback`, `IssuerReponseTimeframeExpired`, `Unknown`. | | SCHEME\_REASON\_CODE | STRING | Scheme-specific reason code, when provided by the PSP. | | LIABILITY\_SHIFTED | BOOLEAN | Whether 3DS liability shift applied to this dispute. | | BIN | STRING | Bank Identification Number of the card used in the original payment. Blank for external disputes or non-card payments. | | ISSUER\_COUNTRY\_CODE | STRING | ISO country code of the card-issuing bank. | | SHOPPER\_COUNTRY\_CODE | STRING | ISO country code of the shopper, when sent on the original payment. | | ARN | STRING | Acquirer Reference Number, once assigned by the acquirer. | ## Related topics - [Reports](/docs/analytics-and-reporting/reports/index.md) - [Enroll Descriptors for Dispute Alerts](/reference/enrolldisputealert.md) - [MangoPay](/docs/analytics-and-reporting/getting-started/connect-your-data-sources/mangopay.md)