Developers

Search for documents

Dev

Disputes

Operations related to disputes

All endpoints require a JWT Bearer token in the Authorization header; most also require an API key in the X-API-KEY header.

GET `/v1/disputes`

Get a list of disputes with pagination

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer`	Yes	Maximum number of records to return. Starts from 1 to 1000.
`page`	query	`integer`	Yes	Page number to retrieve, starting from 0.
`selectFields`	query	`string`	No	Choose specific fields to include in the response (comma-separated).
`filter`	query	`string`	No	A JSON object representing the filter criteria in MongoDB Query Language (MQL) format.
`sort`	query	`string`	No	A JSON object representing the sort criteria in MongoDB Query Language (MQL) format.
`populateOptions`	query	`string`	No	Include related data in query results using a JSON object.

Responses

Status	Description
`200`	Successfully retrieved a paginated list of disputes.

GET `/v1/disputes/{id}`

Get a specific dispute by ID

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The disputeId field
`enriched`	query	`boolean`	No	Include transaction data in the response. When true, enriches the dispute with transaction data where dispute.paymentPspReference === transaction.transactionId.
`selectFields`	query	`string`	No	Choose specific fields to include in the response (comma-separated).
`populateOptions`	query	`string`	No	Include related data in query results using a JSON object.

Responses

Status	Description
`200`	Dispute details retrieved successfully

The following endpoints are served from https://payments.valpay.com.

GET `/v1/disputes/get-defense-reasons/{id}`

Get disputes defense reasons

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Dispute Transaction PSP reference (id)

Responses

Status	Description
`200`	Disputes defense reasons retrieved successfully

Response schema (2xx)

Field	Type	Required	Description
`data`	`object`	Yes
`message`	`string`	Yes	Success message

POST `/v1/disputes/accept-dispute`

Accept a dispute

Request body (required)

Field	Type	Required	Description
`transactionId`	`string`	Yes	Transaction ID

Responses

Status	Description
`200`	Dispute accepted successfully

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes	Response data
`message`	`string`	Yes	Success message

POST `/v1/disputes/defend-dispute`

Defend a dispute

Request body (required)

Field	Type	Required	Description
`transactionId`	`string`	Yes	Transaction ID
`defenseReasonCode`	`string`	Yes	Code identifying the defense reason

Responses

Status	Description
`200`	Dispute defense initiated successfully

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes	Response data
`message`	`string`	Yes	Success message

POST `/v1/disputes/supply-defense-document`

Supply a defense document for a dispute

Request body (required)

Field	Type	Required	Description
`transactionId`	`string`	Yes	Transaction ID
`defenseDocuments`	`array<object>`	Yes	Array of defense documents

Responses

Status	Description
`200`	Defense document supplied successfully

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

POST `/v1/disputes/delete-defense-document`

Delete a defense document from a dispute

Request body (required)

Field	Type	Required	Description
`transactionId`	`string`	Yes	Transaction ID (PSP reference of the dispute)
`defenseDocumentTypeCode`	`string`	Yes	The document type code of the defense document to delete

Responses

Status	Description
`200`	Defense document deleted successfully

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

Examples

GET `/v1/disputes`

First page of open (Notified) disputes, newest first:

curl "https://api.valpay.com/v1/disputes?limit=50&page=0&filter=%7B%22status%22%3A%22Notified%22%7D&sort=%7B%22createdAt%22%3A-1%7D" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/disputes?limit=50&page=0&filter=%7B%22status%22%3A%22Notified%22%7D&sort=%7B%22createdAt%22%3A-1%7D" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/disputes?limit=50&page=0&filter=%7B%22status%22%3A%22Notified%22%7D&sort=%7B%22createdAt%22%3A-1%7D" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Response 200 (illustrative):

{
  "data": [
    {
      "_id": "665f1e2a9c8b4a0012d3e4f7",
      "disputeId": "DSP_EXAMPLE_001",
      "status": "Notified",
      "defendable": true,
      "paymentPspReference": "PSPREF_EXAMPLE_123",
      "amount": { "value": 4250, "currency": "USD" },
      "createdAt": "2026-05-28T14:03:21.000Z"
    }
  ],
  "total": 120,
  "page": 0,
  "limit": 50
}

{
  "data": [
    {
      "_id": "665f1e2a9c8b4a0012d3e4f7",
      "disputeId": "DSP_EXAMPLE_001",
      "status": "Notified",
      "defendable": true,
      "paymentPspReference": "PSPREF_EXAMPLE_123",
      "amount": { "value": 4250, "currency": "USD" },
      "createdAt": "2026-05-28T14:03:21.000Z"
    }
  ],
  "total": 120,
  "page": 0,
  "limit": 50
}

{
  "data": [
    {
      "_id": "665f1e2a9c8b4a0012d3e4f7",
      "disputeId": "DSP_EXAMPLE_001",
      "status": "Notified",
      "defendable": true,
      "paymentPspReference": "PSPREF_EXAMPLE_123",
      "amount": { "value": 4250, "currency": "USD" },
      "createdAt": "2026-05-28T14:03:21.000Z"
    }
  ],
  "total": 120,
  "page": 0,
  "limit": 50
}

GET `/v1/disputes/{id}`

Fetch a dispute enriched with its transaction:

curl "https://api.valpay.com/v1/disputes/DSP_EXAMPLE_001?enriched=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/disputes/DSP_EXAMPLE_001?enriched=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/disputes/DSP_EXAMPLE_001?enriched=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

POST `/v1/disputes/defend-dispute`

curl -X POST https://payments.valpay.com/v1/disputes/defend-dispute \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "PSPREF_EXAMPLE_123",
    "defenseReasonCode": "SupplyDefenseMaterial"
  }'

curl -X POST https://payments.valpay.com/v1/disputes/defend-dispute \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "PSPREF_EXAMPLE_123",
    "defenseReasonCode": "SupplyDefenseMaterial"
  }'

curl -X POST https://payments.valpay.com/v1/disputes/defend-dispute \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "PSPREF_EXAMPLE_123",
    "defenseReasonCode": "SupplyDefenseMaterial"
  }'

Response 200:

{
  "success": true,
  "data": {},
  "message": "Dispute defense initiated successfully"
}

{
  "success": true,
  "data": {},
  "message": "Dispute defense initiated successfully"
}

{
  "success": true,
  "data": {},
  "message": "Dispute defense initiated successfully"
}

Try it out

POST

Guides

Getting Started

Authentication

Pagination

Filtering, Sorting & Fields

api

Disputes

GET /v1/disputes

Parameters

Responses

GET /v1/disputes/{id}

Parameters

Responses

GET /v1/disputes/get-defense-reasons/{id}

Parameters

Responses

Response schema (2xx)

POST /v1/disputes/accept-dispute

Request body (required)

Responses

Response schema (2xx)

POST /v1/disputes/defend-dispute

Request body (required)

Responses

Response schema (2xx)

POST /v1/disputes/supply-defense-document

Request body (required)

Responses

Response schema (2xx)

POST /v1/disputes/delete-defense-document

Request body (required)

Responses

Response schema (2xx)

Examples

GET /v1/disputes

GET /v1/disputes/{id}

POST /v1/disputes/defend-dispute

GET `/v1/disputes`

GET `/v1/disputes/{id}`

GET `/v1/disputes/get-defense-reasons/{id}`

POST `/v1/disputes/accept-dispute`

POST `/v1/disputes/defend-dispute`

POST `/v1/disputes/supply-defense-document`

POST `/v1/disputes/delete-defense-document`

GET `/v1/disputes`

GET `/v1/disputes/{id}`

POST `/v1/disputes/defend-dispute`