Disputes
Formally challenge a payment for reversal, fraud, or service issues.
Overview
Disputes are the formal mechanism for challenging a completed payment. You open a dispute, the recipient organization submits evidence in response, and a Wallgent admin resolves it. The outcome determines which party receives the held funds.
Dispute types:
| Type | Use When |
|---|---|
REVERSAL | A payment was made in error and needs to be unwound |
FRAUD | A payment was made without authorization |
SERVICE_ISSUE | Goods or services contracted for were not delivered |
Dispute lifecycle:
OPEN → RESPONDED (merchant submits evidence)
↓
RESOLVED_AGENT (funds returned to initiator)
RESOLVED_MERCHANT (funds remain with merchant)
CLOSED (administratively closed)Opening a Dispute
POST /v1/disputesRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
transactionId | string | Yes | The txn_ ID of the payment to dispute |
respondentOrgId | string | No | The organization that received the payment (resolved automatically if omitted) |
type | string | Yes | REVERSAL, FRAUD, or SERVICE_ISSUE |
amount | string | Yes | Amount in dispute (decimal string) |
reason | string | Yes | Clear description of the dispute basis |
const response = await fetch('https://api.wallgent.com/v1/disputes', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
transactionId: 'txn_01J...',
type: 'SERVICE_ISSUE',
amount: '250.00',
reason: 'Data processing pipeline was not delivered within the agreed SLA',
}),
})
const dispute = await response.json()
console.log('Dispute opened:', dispute.id)Listing Disputes
GET /v1/disputes?status=...&limit=...&offset=...Returns disputes where your organization is either the initiator or the respondent.
const response = await fetch('https://api.wallgent.com/v1/disputes?status=OPEN', {
headers: { 'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}` },
})
const { data } = await response.json()Query Parameters
| Parameter | Description |
|---|---|
status | Filter by status: OPEN, RESPONDED, RESOLVED_AGENT, RESOLVED_MERCHANT, CLOSED |
limit | Max results (default: 50) |
offset | Pagination offset |
Getting Dispute Details
GET /v1/disputes/:idconst response = await fetch(`https://api.wallgent.com/v1/disputes/${disputeId}`, {
headers: { 'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}` },
})
const dispute = await response.json()Merchant Response (Submitting Evidence)
If your organization is the respondent (the one who received the disputed payment), you can submit evidence to support your case.
POST /v1/disputes/:id/respondRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
response | string | Yes | Written explanation and evidence summary |
evidenceUrl | string | No | URL to supporting documents |
await fetch(`https://api.wallgent.com/v1/disputes/${disputeId}/respond`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.WALLGENT_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
response: 'The pipeline was delivered on 2026-02-28 as confirmed by the attached completion report.',
evidenceUrl: 'https://storage.example.com/evidence/dispute-123.pdf',
}),
})Resolution (Admin Only)
Disputes are resolved by a Wallgent admin. The resolution outcomes are:
| Resolution | Description |
|---|---|
RESOLVED_AGENT | Funds returned to the initiator (agent / buyer wins) |
RESOLVED_MERCHANT | Funds remain with the respondent (merchant wins) |
CLOSED | Dispute closed without a financial remedy |
POST /v1/disputes/:id/resolveWhat Happens to Funds During a Dispute
When a dispute is opened, the contested amount is moved to a suspense account (acc_SUSPENSE) where it is held until the dispute is resolved. Neither party can access the funds during this period.
Disputed funds → acc_SUSPENSE (held)
↓
Resolution outcome
↓
RESOLVED_AGENT → funds → initiator's wallet
RESOLVED_MERCHANT → funds → respondent's wallet
CLOSED → funds returned to original positionsAPI Endpoints
| Method | Path | Description |
|---|---|---|
POST | /v1/disputes | Open a dispute |
GET | /v1/disputes | List disputes |
GET | /v1/disputes/:id | Get dispute details |
POST | /v1/disputes/:id/respond | Submit evidence as the respondent |
POST | /v1/disputes/:id/resolve | Resolve a dispute (admin only) |
Permissions
| Permission | Required For |
|---|---|
payments:write | Open disputes and submit evidence |
payments:read | List and view disputes |