When a customer disputes a card payment, we assemble the evidence from your own records, write a response for the reason the customer's bank gave, attach a PDF of it all with the customer's receipt, and fill in your response draft. You review it on the Disputes page, add what only you know, and submit. Nothing is sent to the bank until the response is submitted.
What goes into the pack
| Evidence | Where it comes from |
|---|---|
| The order | What was bought, quantities, discounts, shipping, tax and the total, from your receipt. |
| The customer | Name, email, billing address, and how long they have been your customer. |
| Customer history | Their earlier payments to you that were not disputed, and which used the same card. |
| Checkout verification | 3D Secure, the security code and address checks, the issuer's authorization code, the IP address and its country next to the card's billing country. |
| Device and browser used at purchase | For fraud and “unrecognized” disputes: the browser and system the customer paid from, its full user agent and languages, and earlier payments from the same IP address. Recorded by our checkout on every card payment the customer makes themselves. |
| Saved card | For one-click payments: when the customer saved the card with you, and that they verified their email address before paying. |
| Terms and refund policy | Your terms and refund policy links (Settings, under Payments), and when the customer ticked “I agree” on a link that asks for it. |
| Delivery | The shipping address, and when you added tracking: the carrier, tracking number, status and delivery date. |
| Emails we sent | Receipts, invoices and reminders, refund receipts, and free-trial reminders, with the time each went out. |
| Subscription | The plan, its price and billing period, when they subscribed, every payment on it, and whether and when they canceled. |
| Refunds | Every refund on the payment, with the reference the customer's bank can trace it by. |
Only facts we hold go in. The pack never guesses, and it never fills in a field you have already written: a field is filled while it is empty, or while it still holds what we wrote last time.
The device details come from your hosted checkout, payment links, invoices, the embedded checkout and the Shopify and WooCommerce checkouts, whenever the customer pays by card themselves; renewals and charges you make from the dashboard have none. They are kept with the payment for as long as its record, because a dispute can arrive months later, and are used only as dispute evidence: never on a receipt, never in the API or webhooks. Test-mode payments keep their own, in test mode.
A response for each reason
| Bank's reason | What the response leads with | Filed as |
|---|---|---|
| Fraudulent | 3D Secure, a saved card after email verification, security code and address checks, matching locations, the device and browser used at purchase, earlier undisputed payments. | Checkout details |
| Unrecognized | The receipt we emailed, the name on card statements, the customer's history with you, the device and browser used at purchase. | Messages with the customer |
| Product not received | Tracking and the delivery date; otherwise the receipt and your policies. | Proof of delivery, or messages |
| Not as described | Your refund policy and terms, and how the customer saw them. | Messages with the customer |
| Subscription canceled | When they subscribed, the renewal terms shown at checkout, every payment, and that they had not canceled before this one. | Subscription history |
| Refund not processed | Any refund already made and its trace reference, and your refund policy. | Messages with the customer |
| Duplicate | Whether another payment for the same amount exists that week, and if so what each one was for. | Customer's past orders |
| Declined authorization, processing error, bank couldn't process | The issuer's approval and authorization code, and the receipt. | Checkout details |
| Request for information, other | The receipt, delivery, verification and your policies. | Proof of delivery, or messages |
Each pack also gets our read of the case — strong, fair or weak — and a checklist of what it includes and what only you can add, such as proof of delivery or why no refund is owed. Our read is for you; it is never sent to the bank.
Reviewing and submitting
- Open the dispute on the Disputes page. The evidence pack sits above your response: the checklist, the response we wrote and a PDF to download.
- Edit any field in the response, upload files you have (photos, sign-ins, conversations), and save your draft.
- Choose Rebuild from latest records after adding tracking or a refund policy: fields you edited keep your words.
- Submit once. Evidence can't be changed after it is submitted.
The PDF is attached to the response unless it already holds its maximum of 10 files. Owners and admins build, edit and submit; every member can read the pack.
Automatic building and submission
| Setting | What it does | Default |
|---|---|---|
| Build evidence automatically | Builds the pack when a dispute opens and tells your owners and admins it is ready. | On |
| Submit for me if nobody has | Submits the response for you 1 to 7 days before the deadline (you choose) when no one on your team has. Checked every hour; it never submits in the last 15 minutes before the deadline. | Off |
Change them on the Disputes page, under Evidence automation. Deadline reminders, 3 days and 1 day before, say when the pack is ready and when it will be submitted for you. If an automatic submission doesn't go through, we email your owners and admins straight away so someone can submit before the deadline.
Evidence status in the API
Every dispute from the Disputes API (GET /v1/disputes, GET /v1/disputes/{id}, the dispute.updated webhook and the MCP tools list_disputes and get_dispute) carries its pack as evidence, or null while there is none:
| Field | What it tells you |
|---|---|
status | building right after the dispute opens or while it is rebuilt, ready, or failed (rebuild it from the Disputes page). |
strength | strong, fair or weak: our read of the case once built. For you only; never sent to the bank. |
recommendAccept | true when your own records back the customer. Such a pack is never submitted automatically. |
documentReady | true once the pack's PDF, with the customer's receipt, is attached to the response. |
builtAt | When the pack was last built. |
submittedAt | When the response went in with the pack, by your team or automatically. |
autoSubmitAt | When we'll submit it for you, while that is still ahead: automatic submission is on, nobody has submitted, we don't advise accepting, and the deadline hasn't passed. Otherwise null. |
{
"status": "ready",
"strength": "strong",
"recommendAccept": false,
"documentReady": true,
"builtAt": "2026-10-18T08:31:12.000Z",
"submittedAt": null,
"autoSubmitAt": "2026-10-30T23:59:59.000Z"
}A test-mode key (ak_test_…) reads the packs of your test disputes. Responding still happens on the Disputes page.
Win rate
The top of the Disputes page shows the disputes opened in the last 365 days: the share the bank decided in your favor, the amounts won back and lost, what is still open, how disputes answered with an evidence pack fared against the rest, and the results by reason. Disputes closed without a ruling (refunded first, or an inquiry that ended) aren't counted as won or lost.