Disputes

ZendFi supports a customer-to-merchant dispute flow with optional admin resolution.

1) Request Dispute OTP (Public)

POST /api/v1/payments/{payment_id}/dispute/request-otp

Requests an email OTP used to verify customer ownership before dispute creation.

Request Body

string

required

Customer email associated with the payment.

Response

{
  "payment_id": "0f1b6f0b-02ef-4fd4-bf31-a89f2fb52f54",
  "customer_email": "customer@example.com",
  "expires_at": "2026-03-22T10:31:15.871Z"
}

2) Create Dispute (Public)

POST /api/v1/payments/{payment_id}/dispute

Creates a dispute after customer verification.

Request Body

string

required

Customer email for identity matching and OTP validation.

string

Optional customer wallet used as alternate ownership proof.

string

required

One of: duplicate, unauthorized, product_not_received, other.

string

required

Customer dispute description.

object

Optional evidence object.

string

required

OTP from the request-otp step.

3) List Merchant Disputes

GET /api/v1/merchants/me/disputes

Session-authenticated merchant endpoint.

Query Parameters

limit (default 50, max 100)
offset (default 0)
status (open, under_review, resolved_merchant_favor, resolved_customer_favor, closed)
dispute_type (duplicate, unauthorized, product_not_received, other)
start_date and end_date

4) Get Dispute Detail

GET /api/v1/merchants/me/disputes/{id}

5) Merchant Respond to Dispute

POST /api/v1/merchants/me/disputes/{id}/respond

Request Body

string

required

Merchant response text.

object

Optional structured evidence payload.

6) Merchant Issue Refund From Dispute

POST /api/v1/merchants/me/disputes/{id}/issue-refund

Creates a linked refund through the refunds system and resolves dispute to customer favor.

Request Body

number

required

Refund amount to issue.

string

Refund reason.

object

Optional metadata forwarded to the refund request.

7) Admin Resolve Dispute

POST /admin/disputes/{id}/resolve

Admin-authenticated endpoint for final resolution.

Request Body

string

required

merchant_favor, customer_favor, or closed.

string

Optional admin notes.

Dispute Statuses

Status	Meaning
`open`	Dispute created, pending merchant action
`under_review`	Merchant responded / evidence review in progress
`resolved_merchant_favor`	Final decision in merchant favor
`resolved_customer_favor`	Final decision in customer favor
`closed`	Dispute closed without favor designation

Dispute Lifecycle Events

DisputeOpened
DisputeResponded
DisputeResolved

See Webhooks.

​Disputes

​1) Request Dispute OTP (Public)

​Request Body

​Response

​2) Create Dispute (Public)

​Request Body

​3) List Merchant Disputes

​Query Parameters

​4) Get Dispute Detail

​5) Merchant Respond to Dispute

​Request Body

​6) Merchant Issue Refund From Dispute

​Request Body

​7) Admin Resolve Dispute

​Request Body

​Dispute Statuses

​Dispute Lifecycle Events

Disputes

1) Request Dispute OTP (Public)

Request Body

Response

2) Create Dispute (Public)

Request Body

3) List Merchant Disputes

Query Parameters

4) Get Dispute Detail

5) Merchant Respond to Dispute

Request Body

6) Merchant Issue Refund From Dispute

Request Body

7) Admin Resolve Dispute

Request Body

Dispute Statuses

Dispute Lifecycle Events