TagPayTagPay

API Reference

Disputes

A Dispute represents a chargeback raised against a settled charge by the cardholder's bank. Merchants cannot open disputes — the card network does. You respond by uploading supporting evidence before the SLA expires.

List disputes

GET/v1/disputes

Returns disputes in reverse-chronological order. Filter by status to triage your response queue, or by date range to audit a period.

Query parameters

statusenum<'open' | 'awaiting-evidence' | 'resolved' | 'closed'>optional

Filter by lifecycle state. open = just raised, no evidence yet. awaiting-evidence = evidence submitted, awaiting review. resolved = final ruling reached. closed = SLA expired without a response.

fromstringoptional

ISO-8601 date — start of created_at range.

tostringoptional

ISO-8601 date — end of created_at range.

pageintegeroptional

Page number, 1-indexed. Default 1.

per_pageintegeroptional

Results per page, max 100. Default 20.

Response

200
dataarray<Dispute>

Array of dispute objects.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

page_countinteger

Total page count.

Retrieve a dispute

GET/v1/disputes/:code

Returns the full dispute resource including all attached evidence. Each evidence entry includes a short-lived presigned_url you can use to download the original upload.

Path parameters

codestringrequired

Dispute code, prefixed with DSP_.

Response

200
idstring

TagPay-assigned dispute ID (UUID).

dispute_codestring

Human-facing code, prefixed with `DSP_`.

transaction_idstring

ID of the disputed transaction.

referencestring

Merchant reference of the disputed transaction.

amountinteger

Disputed amount in kobo.

currencystring

ISO 4217 currency code. Always `NGN` today.

reasonstring

Reason supplied by the issuing bank.

statusenum<'open' | 'awaiting-evidence' | 'resolved' | 'closed'>

Dispute lifecycle state.

due_datestring

ISO-8601 timestamp — last moment to upload evidence before the dispute auto-closes.

resolutionenum<'merchant-won' | 'customer-won'> | null

Final ruling. `null` until `status` becomes `resolved`.

resolution_messagestring | null

Free-text explanation supplied with the ruling.

resolved_atstring | null

ISO-8601 timestamp the dispute was resolved.

evidencearray<Evidence>

Attached evidence files. Empty array if none uploaded yet.

idstring

Evidence ID.

file_namestring

Original filename as uploaded.

file_mime_typestring

MIME type — one of `application/pdf`, `image/jpeg`, `image/png`.

file_size_bytesinteger

Size of the uploaded file in bytes.

presigned_urlstring | null

Short-lived signed download URL for the file. May be `null` if signing failed.

customer_emailstring | null

Customer email supplied with the evidence, if any.

customer_namestring | null

Customer name supplied with the evidence, if any.

delivery_addressstring | null

Delivery address supplied with the evidence, if any.

delivery_datestring | null

ISO-8601 delivery date supplied with the evidence, if any.

descriptionstring | null

Free-text description supplied with the evidence, if any.

created_atstring

ISO-8601 upload timestamp.

created_atstring

ISO-8601 timestamp the dispute was opened.

updated_atstring

ISO-8601 timestamp of the last mutation.

Errors

NOT_FOUND404No dispute with that code on this merchant account.

Upload dispute evidence

POST/v1/disputes/:code/evidence

Sent as multipart/form-data. The document part is the file (PDF, JPEG, or PNG; max 10 MB). All other fields are optional text context that travels with the file. The first successful upload promotes the dispute from open to awaiting-evidence; subsequent uploads leave the status unchanged.

Path parameters

codestringrequired

Dispute code, prefixed with DSP_.

Form fields (multipart/form-data)

documentfilerequired

The evidence file. PDF, JPEG, or PNG only. Max **10 MB**. Sent as a multipart file field.

customer_emailstringoptional

Email of the customer involved.

customer_namestringoptional

Name of the customer involved. Max 200 characters.

delivery_addressstringoptional

Delivery address if disputing a goods-not-received claim. Max 500 characters.

delivery_datestringoptional

ISO-8601 delivery date if applicable.

descriptionstringoptional

Free-text context describing what the file proves. Max 2000 characters.

Response

201
idstring

Evidence ID.

file_namestring

Original filename.

file_mime_typestring

MIME type of the uploaded file.

file_size_bytesinteger

Size of the file in bytes.

presigned_urlstring | null

Short-lived signed download URL.

customer_emailstring | null

Echoed customer email, if supplied.

customer_namestring | null

Echoed customer name, if supplied.

delivery_addressstring | null

Echoed delivery address, if supplied.

delivery_datestring | null

Echoed delivery date, if supplied.

descriptionstring | null

Echoed description, if supplied.

created_atstring

ISO-8601 upload timestamp.

Errors

NOT_FOUND404No dispute with that code on this merchant account.
BAD_REQUEST400No file uploaded, file exceeds the 10 MB limit, or MIME type is not in the allowed list (`application/pdf`, `image/jpeg`, `image/png`).
CONFLICT409Cannot upload evidence on a dispute that has already been resolved or closed.