Uprails API Reference

Overview

A dispute (also known as a chargeback) occurs when a cardholder questions a payment with their card issuer. When this happens, the card issuer creates a formal dispute which immediately reverses the payment.

The Disputes API allows you to:

View dispute details and status
Accept disputes when appropriate
Track dispute outcomes
List and filter all disputes

Dispute Object

Dispute Objectjson

{
  "dispute_id": "dis_1234567890abcdef",
  "payment_id": "pay_abcdef1234567890",
  "merchant_id": "mer_xyz789",
  "status": "needs_response",
  "amount": 1000,
  "currency": "USD",
  "reason": "fraudulent",
  "evidence_due_by": "2024-01-25T23:59:59Z",
  "metadata": {},
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z"
}

API Endpoints

GET/disputes/:idRetrieve Dispute POST/disputes/:id/acceptAccept Dispute GET/disputes/listList Disputes

Dispute Status

A dispute progresses through several statuses:

Status	Description
`needs_response`	Dispute opened, evidence submission required
`under_review`	Evidence submitted, awaiting card issuer decision
`won`	Dispute resolved in your favor, funds returned
`lost`	Dispute resolved in customer's favor
`accepted`	You accepted the dispute without contesting
`expired`	Evidence deadline passed without response

Dispute Reasons

Common reasons for disputes include:

Reason	Description
`fraudulent`	Customer claims they didn't authorize the payment
`unrecognized`	Customer doesn't recognize the transaction
`product_not_received`	Customer didn't receive the product or service
`product_unacceptable`	Product or service was defective or not as described
`duplicate`	Customer was charged multiple times
`subscription_canceled`	Customer was charged after canceling

Dispute Lifecycle

Dispute Opened

A customer disputes a payment. Funds are immediately debited from your account.

Evidence Required

You have a limited time (typically 7-21 days) to submit evidence or accept the dispute.

Review Period

The card issuer reviews the evidence and makes a decision (can take 60-90 days).

Resolution

The dispute is resolved as won (funds returned) or lost (funds remain with customer).

Important Deadlines

Evidence must be submitted before the evidence_due_by deadline. Missing this deadline automatically results in losing the dispute.