API Reference›Disputes

Disputes

A dispute (chargeback) is raised when a customer contacts their bank to contest a charge. The Disputes API lets you list open disputes, retrieve individual dispute details, upload evidence to challenge a dispute, and submit a final resolution.

Provider support

Dispute management is supported by Paystack and Flutterwave. Disputes are created by the provider when a chargeback is raised and synced to POPFAB via webhook. You cannot create disputes through the API — you can only respond to disputes that already exist.

Endpoints

GET/v1/disputes— List disputes (paginated)

GET/v1/disputes/:id— Retrieve a single dispute

POST/v1/disputes/:id/evidence— Upload evidence for a dispute

POST/v1/disputes/:id/resolve— Submit resolution for a dispute

List Disputes

GET

/v1/disputes

Returns a cursor-paginated list of disputes for your merchant account, newest first.

Query parameters

Parameter	Type	Required	Description
`status`	`string`	Optional	Filter by dispute status: open, awaiting-merchant-feedback, under-review, resolved, won, lost.
`limit`	`integer`	Optional	Results per page. Default 20, max 100.
`cursor`	`string`	Optional	Pagination cursor from a previous response next_cursor field.

List open disputesbash

curl "https://api.popfab.io/v1/disputes?status=open" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Get a Dispute

GET

/v1/disputes/:id

Retrieves the current state of a single dispute including any uploaded evidence and resolution details.

Get dispute by IDbash

curl https://api.popfab.io/v1/disputes/ppfb_dsp_01HXA3KBZQM4Z3YWN5E6R7VP8S \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Submit Evidence

Upload supporting documentation to challenge a dispute. Evidence must be submitted before calling the resolve endpoint. Acceptable evidence types include delivery confirmations, customer communications, and service agreements.

POST

/v1/disputes/:id/evidence

Attaches evidence to a dispute. Evidence is forwarded to the provider for review.

Request body

Parameter	Type	Required	Description
`customer_email`	`string`	Optional	Email address used by the customer at the time of purchase.
`customer_name`	`string`	Optional	Full name of the customer.
`customer_phone`	`string`	Optional	Phone number of the customer.
`service_details`	`string`	Optional	Description of the product or service delivered.
`delivery_address`	`string`	Optional	Shipping address for physical goods.
`delivery_date`	`string`	Optional	Date goods or services were delivered (YYYY-MM-DD).
`uploaded_filename`	`string`	Optional	Filename of a previously uploaded file (PDF or image) to attach as supporting evidence.

Submit evidencebash

curl -X POST https://api.popfab.io/v1/disputes/ppfb_dsp_01HXA3KBZQM4Z3YWN5E6R7VP8S/evidence \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "ada@example.com",
    "customer_name": "Ada Okafor",
    "service_details": "Premium subscription — March 2026. Service was active from 2026-03-01.",
    "delivery_date": "2026-03-01",
    "uploaded_filename": "delivery_confirmation.pdf"
  }'

Resolve a Dispute

After uploading evidence (if any), submit your final resolution decision. If you accept the dispute, optionally specify a refund amount. If you decline, your previously submitted evidence is forwarded to the issuing bank for review.

POST

/v1/disputes/:id/resolve

Submits the merchant's resolution decision for a dispute.

Request body

Parameter	Type	Required	Description
`resolution`	`string`	Required	Your resolution decision: merchant-accepted (you accept the chargeback) or declined (you are contesting the dispute).
`refund_amount`	`integer`	Optional	Amount to refund in the smallest currency unit (kobo for NGN). Only applicable when resolution is merchant-accepted. Defaults to the full disputed amount.
`uploaded_filename`	`string`	Optional	Filename of additional supporting documentation to attach at resolution time.

Decline a dispute (contest it)bash

curl -X POST https://api.popfab.io/v1/disputes/ppfb_dsp_01HXA3KBZQM4Z3YWN5E6R7VP8S/resolve \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "declined"
  }'

Accept a dispute with partial refundbash

curl -X POST https://api.popfab.io/v1/disputes/ppfb_dsp_01HXA3KBZQM4Z3YWN5E6R7VP8S/resolve \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "merchant-accepted",
    "refund_amount": 250000
  }'

⚠

Always submit evidence before calling resolve. If you call resolve with resolution: declined without first uploading evidence, the dispute will be forwarded to the bank with no supporting documentation, reducing your chance of winning the chargeback.

Dispute Statuses

Status	Description
open	A new dispute has been raised. Action required.
awaiting-merchant-feedback	The provider is waiting for you to submit evidence or accept the dispute.
under-review	Your evidence has been submitted and is being reviewed by the bank.
resolved	The dispute has been resolved. Check won or lost for the outcome.
won	The bank ruled in your favour. No funds were deducted.
lost	The bank ruled in the customer's favour. Funds were reversed.

← Identity (KYC)Next: Error Reference →