Build a dispute's evidence pack

Builds the evidence pack of a dispute that needs a response: one PDF with what Ownrecord recorded about the disputed sale. Its sections: the invoice (whose PDF is sent along as the receipt), the customer's IP country at purchase (with the billing and card countries), the usage since the payment, the terms acceptance with its timestamp, the customer portal sign-ins, and the waiver of the right of withdrawal. A section with nothing recorded says so; evidence.sections tells which have content.

The PDF is stored privately and previewed in the console; disputes.evidence.get returns the pack's content. Building again replaces the pack. Nothing is sent to the processor until disputes.submit_evidence.

At a glance

REST: POST /api/v1/disputes/{id}/evidence
MCP tool: disputes_evidence_build
Operation ID: disputes.evidence.build
Scope: Brand
Permission: disputes:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the disputes:write scope
Since: M8

Request

Path parameters

Field	Type	Description
`id`	`dp_…` ID

Body

This operation takes no body.

Response

201 Created with a JSON object:

Field	Type	Description
`id`	`dp_…` ID
`object`	`"dispute"`
`livemode`	boolean
`entityId`	`ent_…` ID
`brandId`	`brd_…` ID
`paymentId`	`pay_…` ID
`customerId`	`cus_…` ID
`processor`	one of `stripe`, `mollie`, `fake`
`processorConnectionId`	`pcon_…` ID
`processorRef`	string
`reason`	string or null
`processorStatus`	string or null
`status`	one of `needs_response`, `under_review`, `won`, `lost`
`inquiry`	boolean
`fundsWithdrawnAt`	date-time or null
`amount`	money
`fee`	money or null
`evidenceDueBy`	date-time or null
`openedAt`	date-time
`closedAt`	date-time or null
`ledgerTxnIds`	array of `txn_…` ID
`walletFreeze`	object or null
`walletReversal`	object or null
`evidence`	object or null
`notes`	string or null
`assignee`	object or null
`history`	array of object
`history[].at`	date-time
`history[].event`	one of 10 values, e.g. `opened`, `wallet_frozen`, `funds_withdrawn` (all in the OpenAPI document)
`history[].by`	string
`history[].note`	string or null
`createdAt`	date-time
`updatedAt`	date-time
`version`	integer (at least 1)

Examples

Build the pack of a new chargeback

HTTP

POST /api/v1/disputes/dp_01m4ttwd3veh9apbewxheq5xb1/evidence
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

Response (201):

JSON

{
  "id": "dp_01m4ttwd3veh9apbewxheq5xb1",
  "object": "dispute",
  "livemode": true,
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
  "paymentId": "pay_01m4ttwd3veh9apbewxheq5xb2",
  "customerId": "cus_01m4ttwd3veh9apbewxheq5xb3",
  "processor": "stripe",
  "processorConnectionId": "pcon_01m4ttwd3veh9apbewxheq5xb4",
  "processorRef": "dp_1QOwnrecordTest01",
  "reason": "fraudulent",
  "processorStatus": "needs_response",
  "status": "needs_response",
  "inquiry": false,
  "fundsWithdrawnAt": "2026-10-18T08:00:00.000Z",
  "amount": {
    "amount": "12500000",
    "currency": "EUR"
  },
  "fee": {
    "amount": "15000000",
    "currency": "EUR"
  },
  "evidenceDueBy": "2026-10-25T23:59:59.000Z",
  "openedAt": "2026-10-18T08:00:00.000Z",
  "closedAt": null,
  "ledgerTxnIds": ["txn_01m4ttwd3veh9apbewxheq5xb6"],
  "walletFreeze": {
    "walletIds": ["wal_01m4ttwd3veh9apbewxheq5xb5"],
    "frozenAt": "2026-10-18T08:00:00.000Z",
    "unfrozenAt": null
  },
  "walletReversal": {
    "walletId": "wal_01m4ttwd3veh9apbewxheq5xb5",
    "credits": {
      "amount": "10000000",
      "currency": "EUR"
    },
    "restored": null
  },
  "evidence": {
    "fileId": "file_01m4ttwd3veh9apbewxheq5xb7",
    "sha256": "3f1c6d2b9a7e4f0812c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b",
    "size": 48211,
    "builtAt": "2026-10-19T09:30:00.000Z",
    "builtBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
    "sections": {
      "invoice": true,
      "ip_country": true,
      "usage": true,
      "terms": true,
      "sign_ins": false,
      "waiver": true
    },
    "receiptFileId": "file_01m4ttwd3veh9apbewxheq5xb8",
    "submittedAt": null,
    "submittedBy": null,
    "processorFileRefs": []
  },
  "notes": null,
  "assignee": null,
  "history": [
    {
      "at": "2026-10-18T08:00:00.000Z",
      "event": "opened",
      "by": "system",
      "note": null
    },
    {
      "at": "2026-10-18T08:00:00.000Z",
      "event": "wallet_frozen",
      "by": "system",
      "note": "1 wallet"
    },
    {
      "at": "2026-10-18T08:00:00.000Z",
      "event": "funds_withdrawn",
      "by": "system",
      "note": null
    },
    {
      "at": "2026-10-19T09:30:00.000Z",
      "event": "evidence_built",
      "by": "usr_01m4ttwd3veh9apbewxheq5xh6",
      "note": null
    }
  ],
  "createdAt": "2026-10-18T08:00:00.000Z",
  "updatedAt": "2026-10-19T09:30:00.000Z",
  "version": 3
}

Errors

Code	HTTP status	When	What to do
`resource_not_found`	404	No dispute with this ID in this brand and mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`dispute_status_invalid`	409	The dispute doesn't need a response any more (its evidence was submitted, or it closed).	Reload the dispute. Evidence is built and submitted only while the dispute needs a response (`needs_response`); once submitted (`under_review`) or closed (`won`, `lost`) it can't change. `details.status` is the dispute's status.
`upstream_timeout`	502	The file store didn't answer in time; nothing was recorded. Retry.	Retry the request with the same Idempotency-Key after a short wait.
`version_conflict`	409	The dispute changed at the same moment; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't work on disputes of this brand.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Build the pack of a new chargeback#

Errors#