Disputes

The DisputeResource allows you to manage transaction disputes on your integration. You can list, fetch, update, and resolve disputes, as well as provide evidence for fraud claims.

List Disputes

List disputes filed against your integration.

// List all disputes
$disputes = paystack()->dispute()->list();

// Filter disputes
$filtered = paystack()->dispute()->list([
    'from' => '2023-01-01',
    'to' => '2023-12-31',
    'status' => 'awaiting-merchant-feedback'
]);

Parameters

Parameter	Type	Required	Description
from	Date	No	A timestamp from which to start listing disputes.
to	Date	No	A timestamp at which to stop listing disputes.
perPage	Integer	No	Specify how many records you want to retrieve per page.
page	Integer	No	Specify exactly what page you want to retrieve.
transaction	String	No	Transaction ID.
status	String	No	Dispute Status. Values: awaiting-merchant-feedback, awaiting-bank-feedback, pending, resolved.

Fetch Dispute

Get more details about a specific dispute.

$disputeId = 12345;
$details = paystack()->dispute()->fetch($disputeId);

List Transaction Disputes

Retrieve disputes for a particular transaction.

$transactionId = 5991760;
$disputes = paystack()->dispute()->listByTransaction($transactionId);

Update Dispute

Update details of a dispute, such as the refund amount.

$disputeId = 12345;
$response = paystack()->dispute()->update($disputeId, [
    'refund_amount' => 1000 // Amount in kobo
]);

Add Evidence

Provide evidence for a dispute (especially for fraud claims) to prove the service was rendered.

$disputeId = 12345;
$response = paystack()->dispute()->addEvidence($disputeId, [
    'customer_email' => '[email protected]',
    'customer_name' => 'Mensah King',
    'customer_phone' => '0802345167',
    'service_details' => 'Claim for buying product',
    'delivery_address' => '3a ladoke street ogbomoso'
]);

Get Upload URL

Get a signed URL to upload a file (PDF/Image) as evidence for a dispute.

$disputeId = 12345;
$filename = 'receipt.pdf';

$response = paystack()->dispute()->getUploadUrl($disputeId, $filename);

$signedUrl = $response['data']['signedUrl'];
$uploadFilename = $response['data']['fileName'];

// Use the signedUrl to upload the file via a PUT request

Resolve Dispute

Resolve a dispute on your integration by either accepting or declining it.

$disputeId = 12345;

// Accept Dispute
$response = paystack()->dispute()->resolve($disputeId, [
    'resolution' => 'merchant-accepted',
    'message' => 'Merchant accepted',
    'refund_amount' => 1000
]);

// Decline Dispute (requires evidence)
$response = paystack()->dispute()->resolve($disputeId, [
    'resolution' => 'declined',
    'message' => 'Service was rendered',
    'uploaded_filename' => 'qesp8a4df1xejihd9x5q' // Filename from getUploadUrl
]);

Export Disputes

Export disputes available on your integration as a report.

$response = paystack()->dispute()->export([
    'from' => '2023-01-01',
    'to' => '2023-12-31'
]);

Automating Dispute Resolution

You can automate the process of handling disputes by creating a background task that runs periodically.

Step 1: Get Pending Disputes

Retrieve all disputes with the status awaiting-merchant-feedback.

$pendingDisputes = paystack()->dispute()->list([
    'status' => 'awaiting-merchant-feedback',
    'from' => now()->subDays(1)->toIso8601String(),
    'to' => now()->toIso8601String()
]);

Step 2: Upload Evidence

For each dispute, find the corresponding transaction receipt and upload it.

foreach ($pendingDisputes['data'] as $dispute) {
    $transactionRef = $dispute['transaction']['reference'];
    $disputeId = $dispute['id'];
    
    // 1. Get Upload URL
    $uploadData = paystack()->dispute()->getUploadUrl($disputeId, "$transactionRef.pdf");
    $signedUrl = $uploadData['data']['signedUrl'];
    $fileName = $uploadData['data']['fileName'];
    
    // 2. Upload file to signedUrl (using Guzzle or similar)
    // ... implementation of file upload ...
    
    // 3. Resolve Dispute
    paystack()->dispute()->resolve($disputeId, [
        'resolution' => 'declined',
        'message' => 'Receipt attached',
        'uploaded_filename' => $fileName
    ]);
}