Dispute
A collection of endpoints for managing transactions complaint made by customers
Copy link List Disputes
List transaction disputes filed by customers
Query Parameters
Number of records to fetch per page
The section to retrieve
Dispute status
Enumawaiting-merchant-feedbackawaiting-bank-feedbackpendingresolved
Transaction ID
The start date
The end date
Response
200Dispute List response
5 object properties
GET
/disputecurl https://api.paystack.co/dispute \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.list({
perPage: 100,
page: 100
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.list({
per_page: 100,
page: 100
})
puts response.dataResponse
{
"status": true,
"message": "Disputes retrieved",
"data": [
{
"id": 2867,
"refund_amount": null,
"currency": null,
"status": "archived",
"resolution": null,
"domain": "test",
"transaction": {
"id": 5991760,
"domain": "test",
"status": "success",
"reference": "asjck8gf76zd1dr",
"amount": 39100,
"message": null,
"gateway_response": "Successful",
"paid_at": "2017-11-09T00:01:56.000Z",
"created_at": "2017-11-09T00:01:36.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": null,
"metadata": "",
"log": null,
"fees": 587,
"fees_split": null,
"authorization": {},
"customer": null,
"plan": {},
"subaccount": {},
"split": {},
"order_id": null,
"paidAt": "2017-11-09T00:01:56.000Z",
"createdAt": "2017-11-09T00:01:36.000Z",
"pos_transaction_data": null
},
"transaction_reference": null,
"category": null,
"customer": {
"id": 10207,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_unz4q52yjsd6064",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"bin": null,
"last4": null,
"dueAt": null,
"resolvedAt": null,
"evidence": null,
"attachments": "[]",
"note": null,
"history": [
{
"status": "pending",
"by": "[email protected]",
"createdAt": "2017-11-16T16:12:24.000Z"
}
],
"messages": [
{
"sender": "[email protected]",
"body": "test this",
"createdAt": "2017-11-16T16:12:24.000Z"
}
],
"createdAt": "2017-11-16T16:12:24.000Z",
"updatedAt": "2019-08-16T08:05:25.000Z"
}
],
"meta": {
"total": 1,
"skipped": 0,
"perPage": 50,
"page": 1,
"pageCount": 1
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Dispute
Fetch a transaction dispute
Path Parameters
The unique identifier of the dispute
Response
200Dispute Fetch response
21 object properties
30 object properties
1 object property
8 object properties
2 object properties
1 object property
9 object properties
GET
/dispute/{id}curl https://api.paystack.co/dispute/1801929 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.fetch("1801929");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.fetch("1801929")
puts response.dataResponse
{
"status": true,
"message": "Dispute retrieved",
"data": {
"id": 2867,
"refund_amount": null,
"currency": null,
"status": "archived",
"resolution": null,
"domain": "test",
"transaction": {
"id": 5991760,
"domain": "test",
"status": "success",
"reference": "asjck8gf76zd1dr",
"amount": 39100,
"message": null,
"gateway_response": "Successful",
"paid_at": "2017-11-09T00:01:56.000Z",
"created_at": "2017-11-09T00:01:36.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": null,
"metadata": "",
"log": null,
"fees": 587,
"fees_split": null,
"authorization": {},
"customer": {
"international_format_phone": null
},
"plan": {},
"subaccount": {},
"split": {},
"order_id": null,
"paidAt": "2017-11-09T00:01:56.000Z",
"createdAt": "2017-11-09T00:01:36.000Z",
"requested_amount": null
},
"transaction_reference": null,
"category": null,
"customer": {
"id": 10207,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_unz4q52yjsd6064",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"bin": null,
"last4": null,
"dueAt": null,
"resolvedAt": null,
"evidence": null,
"attachments": "[]",
"note": null,
"history": [
{
"status": "pending",
"by": "[email protected]",
"createdAt": "2017-11-16T16:12:24.000Z"
}
],
"messages": [
{
"sender": "[email protected]",
"body": "test this",
"createdAt": "2017-11-16T16:12:24.000Z"
}
],
"createdAt": "2017-11-16T16:12:24.000Z",
"updatedAt": "2019-08-16T08:05:25.000Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Update Dispute
Update a transaction dispute
Path Parameters
The unique identifier of the dispute
Request Body
The amount to refund, in the subunit of your currency
Filename of attachment returned via response from the Dispute upload URL
Response
200Dispute Update response
21 object properties
30 object properties
1 object property
8 object properties
2 object properties
1 object property
9 object properties
PUT
/dispute/{id}curl https://api.paystack.co/dispute/1801929 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"refund_amount": 50000
}' \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.update("1801929", {
refund_amount: 50000
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.update("1801929", {
refund_amount: 50000
})
puts response.dataResponse
{
"status": true,
"message": "Dispute updated successfully",
"data": [
{
"currency": "NGN",
"last4": null,
"bin": null,
"transaction_reference": null,
"merchant_transaction_reference": null,
"refund_amount": 1002,
"status": "resolved",
"domain": "test",
"resolution": "merchant-accepted",
"source": "bank",
"category": "general",
"note": null,
"attachments": "attachement",
"id": 624,
"transaction": {
"id": 5991760,
"domain": "test",
"status": "success",
"reference": "asjck8gf76zd1dr",
"amount": 39100,
"message": null,
"gateway_response": "Successful",
"paid_at": "2017-11-09T00:01:56.000Z",
"created_at": "2017-11-09T00:01:36.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": null,
"metadata": "",
"log": null,
"fees": 587,
"fees_split": null,
"authorization": {},
"customer": {
"international_format_phone": null
},
"plan": {},
"subaccount": {},
"split": {},
"order_id": null,
"paidAt": "2017-11-09T00:01:56.000Z",
"createdAt": "2017-11-09T00:01:36.000Z",
"requested_amount": null
},
"customer": {
"id": 10207,
"first_name": null,
"last_name": null,
"email": "[email protected]",
"customer_code": "CUS_unz4q52yjsd6064",
"phone": null,
"metadata": null,
"risk_action": "default",
"international_format_phone": null
},
"organization": 1,
"evidence": null,
"resolvedAt": "2019-08-28T14:14:41.000Z",
"createdAt": "2019-08-28T14:14:41.000Z",
"updatedAt": "2019-08-28T14:29:07.000Z",
"dueAt": null
}
]
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Upload URL
Get the URL to upload a dispute evidence
Path Parameters
The unique identifier of the dispute
Response
200Dispute Upload URL response
2 object properties
GET
/dispute/{id}/upload_urlcurl https://api.paystack.co/dispute/4734583785/upload_url \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.uploadUrl("4734583785");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.upload_url("4734583785")
puts response.dataResponse
{
"status": true,
"message": "Upload url generated",
"data": {
"signedUrl": "https://s3.eu-west-1.amazonaws.com/files.paystack.co/qesp8a4df1xejihd9x5q?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAI7CL5IZL2DJHOPPA%2F20191009%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20191009T220931Z&X-Amz-Expires=1800&X-Amz-Signature=f5cc387949f3520982886e70ab2e08721a82a9fa9e26b696b91471f36453867a&X-Amz-SignedHeaders=host",
"fileName": "qesp8a4df1xejihd9x5q"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Export Disputes
Export the disputes available on your integration
Query Parameters
Number of records to fetch per page
The section to retrieve
Enumawaiting-merchant-feedbackawaiting-bank-feedbackpendingresolved
The start date
The end date
Response
200Dispute Export response
2 object properties
GET
/dispute/exportcurl https://api.paystack.co/dispute/export \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.download({
perPage: 100,
page: 100
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.download({
per_page: 100,
page: 100
})
puts response.dataResponse
{
"status": true,
"message": "Export successful",
"data": {
"path": "https://s3.eu-west-1.amazonaws.com/files.paystack.co/exports/100043/disputes/161834548008.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIFGL5IZL2DJHOPPA%2F20210419%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20210419T115718Z&X-Amz-Expires=60&X-Amz-Signature=8fc02bdf7f12411a6505559b4c35b069a8a478295b98c0587907777ef5e31bda&X-Amz-SignedHeaders=host",
"expiresAt": "2021-04-19 11:58:18"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link List Transaction Disputes
List all disputes filed for a transaction
Path Parameters
The unique identifier of the transaction
Response
200Dispute List Transaction response
23 object properties
30 object properties
1 object property
8 object properties
2 object properties
1 object property
GET
/dispute/transaction/{id}curl https://api.paystack.co/dispute/transaction/4734583785 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.transaction("4734583785");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.transaction("4734583785")
puts response.dataResponse
{
"status": true,
"message": "Dispute retrieved successfully",
"data": {
"history": [
{
"id": 6094,
"dispute": 2867,
"status": "pending",
"by": "[email protected]",
"createdAt": "2017-11-16T16:12:24.000Z",
"updatedAt": "2017-11-16T16:12:24.000Z"
}
],
"messages": [
{
"sender": "[email protected]",
"body": "test this",
"dispute": 2867,
"id": 148,
"is_deleted": 0,
"createdAt": "2017-11-16T16:12:24.000Z",
"updatedAt": "2017-11-16T16:12:24.000Z"
}
],
"currency": null,
"last4": null,
"bin": null,
"transaction_reference": null,
"merchant_transaction_reference": null,
"refund_amount": null,
"status": "archived",
"domain": "test",
"resolution": null,
"category": null,
"note": null,
"attachments": "[]",
"id": 2867,
"integration": 100043,
"transaction": {
"id": 5991760,
"domain": "test",
"status": "success",
"reference": "asjck8gf76zd1dr",
"amount": 39100,
"message": null,
"gateway_response": "Successful",
"paid_at": "2017-11-09T00:01:56.000Z",
"created_at": "2017-11-09T00:01:36.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": null,
"metadata": "",
"log": null,
"fees": 587,
"fees_split": null,
"authorization": {},
"customer": {
"international_format_phone": null
},
"plan": {},
"subaccount": {},
"split": {},
"order_id": null,
"paidAt": "2017-11-09T00:01:56.000Z",
"createdAt": "2017-11-09T00:01:36.000Z",
"requested_amount": null
},
"created_by": null,
"evidence": null,
"resolvedAt": null,
"createdAt": "2017-11-16T16:12:24.000Z",
"updatedAt": "2019-08-16T08:05:25.000Z",
"dueAt": null
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Resolve Dispute
Resolve a transaction dispute
Path Parameters
The unique identifier of the dispute
Request Body
Dispute resolution. Accepted values, merchant-accepted, declined
Reason for resolving
The amount to refund, in the subunit of your integration currency
Filename of attachment returned via response from the Dispute upload URL
Evidence Id for fraud claims
Response
200Dispute Resolve response
22 object properties
6 object properties
PUT
/dispute/{id}/resolvecurl https://api.paystack.co/dispute/4734583785/resolve \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"resolution": "merchant-accepted",
"message": "Merchant accepted",
"refund_amount": 50000,
"uploaded_filename": "qesp8a4df1xejihd9x5q"
}' \
-X PUTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.resolve("4734583785", {
resolution: "merchant-accepted",
message: "Merchant accepted",
refund_amount: 50000,
uploaded_filename: "qesp8a4df1xejihd9x5q"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.resolve("4734583785", {
resolution: "merchant-accepted",
message: "Merchant accepted",
refund_amount: 50000,
uploaded_filename: "qesp8a4df1xejihd9x5q"
})
puts response.dataResponse
{
"status": true,
"message": "Dispute successfully resolved",
"data": {
"currency": "NGN",
"last4": null,
"bin": null,
"transaction_reference": null,
"merchant_transaction_reference": null,
"refund_amount": 1002,
"status": "resolved",
"domain": "test",
"resolution": "merchant-accepted",
"category": "general",
"note": null,
"attachments": "attachment",
"id": 624,
"transaction": {
"id": 5991760,
"domain": "test",
"status": "success",
"reference": "asjck8gf76zd1dr",
"amount": 39100,
"message": null,
"gateway_response": "Successful",
"paid_at": "2017-11-09T00:01:56.000Z",
"created_at": "2017-11-09T00:01:36.000Z",
"channel": "card",
"currency": "NGN",
"ip_address": null,
"metadata": "",
"log": null,
"fees": 587,
"fees_split": null,
"authorization": {},
"customer": {
"international_format_phone": null
},
"plan": {},
"subaccount": {},
"split": {},
"order_id": null,
"paidAt": "2017-11-09T00:01:56.000Z",
"createdAt": "2017-11-09T00:01:36.000Z",
"requested_amount": null
},
"created_by": 30,
"evidence": null,
"resolvedAt": "2019-08-28T15:23:31.000Z",
"createdAt": "2019-08-28T14:14:41.000Z",
"updatedAt": "2019-08-28T15:23:31.000Z",
"dueAt": null,
"message": {
"dispute": 624,
"sender": "[email protected]",
"body": "Merchant accepted",
"id": 718,
"createdAt": "2019-08-28T15:23:31.418Z",
"updatedAt": "2019-08-28T15:23:31.418Z"
}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Add Evidence
Provide evidence for a dispute
Path Parameters
The unique identifier of the dispute
Request Body
Customer email
Customer name
Customer mobile number
Details of service offered
Delivery address
ISO 8601 representation of delivery date (YYYY-MM-DD)
Response
200Dispute Add Evidence response
10 object properties
POST
/dispute/{id}/evidencecurl https://api.paystack.co/dispute/4734583785/evidence \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_email": "[email protected]",
"customer_name": "Mensah King",
"customer_phone": "+2348123456789",
"service_details": "claim for buying cups"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dispute.evidence("4734583785", {
customer_email: "[email protected]",
customer_name: "Mensah King",
customer_phone: "+2348123456789",
service_details: "claim for buying cups"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dispute.evidence("4734583785", {
customer_email: "[email protected]",
customer_name: "Mensah King",
customer_phone: "+2348123456789",
service_details: "claim for buying cups"
})
puts response.dataResponse
{
"status": true,
"message": "Evidence created",
"data": {
"customer_email": "[email protected]",
"customer_name": "Mensah King",
"customer_phone": "+2348123456789",
"service_details": "claim for buying product",
"delivery_address": "3a ladoke street ogbomoso",
"dispute": 624,
"id": 21,
"createdAt": "2019-08-28T15:36:13.783Z",
"updatedAt": "2019-08-28T15:39:39.153Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}