Disputes

After you mark an order as delivered, the buyer has 24 hours to raise a dispute. If they do, you have 24 hours to resolve it. If you don't, the buyer is automatically refunded.

How Disputes Work

Buyer raises a dispute

Within 24 hours of delivery, the buyer can dispute for two reasons: non-delivery (DISPUTE_DELIVERY) or quality issues (DISPUTE_QUALITY). The auto-confirm timer is paused.

You get notified

You receive a DISPUTE_RAISED webhook and an email to your dispute_email address. The order status changes to DISPUTE_DELIVERY or DISPUTE_QUALITY.

You resolve it (24 hours)

Call the dispute-resolved endpoint with a resolution note. The order goes back to DELIVERED status and a new 24-hour auto-confirm window starts.

Or it auto-refunds

If you don't resolve within 24 hours, the buyer is automatically refunded in full. The order status becomes REFUNDED.

Important: Dispute Rounds

After you resolve a dispute, the buyer can dispute again within the new 24-hour window.
If the same order gets disputed 3 or more times, DoorPay support is automatically notified and may step in to help resolve the issue.
After 5 disputes, the order is frozen and escalated to DoorPay admin for manual resolution. You will not be able to resolve further disputes via the API.
The dispute_count field in the order response tracks how many disputes have been raised.

Resolve Dispute

Resolves an active dispute on an order. The order goes back to DELIVERED status with a fresh 24-hour auto-confirm window. The buyer is notified that you've resolved their concern. You can only call this when the order status is DISPUTE_DELIVERY or DISPUTE_QUALITY.

PUThttps://api.thedoorpay.com/sandbox/api/merchant/v1/orders/{orderNumber}/dispute-resolved

Request Body (JSON) — Optional

Field	Type	Required	Description
`resolution_note`	string	Optional	Explain how you resolved the dispute. Max 1000 characters. Example: "Replacement shipped via BlueDart, tracking: BD123456". Shown to the buyer and stored in the audit trail.

Request with note (sandbox)

curl -X PUT https://api.thedoorpay.com/sandbox/api/merchant/v1/orders/DP-20260313-A7X9K2/dispute-resolved \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_note": "Replacement shipped via BlueDart, tracking: BD123456"
  }'

Request without note (sandbox)

curl -X PUT https://api.thedoorpay.com/sandbox/api/merchant/v1/orders/DP-20260313-A7X9K2/dispute-resolved \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret"

Response (200 OK)

{
  "success": true,
  "message": "Dispute resolved",
  "data": {
    "order_number": "DP-20260313-A7X9K2",
    "status": "DELIVERED",
    "payment_status": "PAID",
    "auto_confirm_at": "2026-03-15T10:00:00Z",
    "dispute_count": 1,
    "last_dispute_at": "2026-03-14T08:00:00Z",
    "audit_trail": [
      { "action_type": "MERCHANT_ORDER_CREATED", "timestamp": "2026-03-13T10:00:00Z" },
      { "action_type": "PAID", "timestamp": "2026-03-13T10:05:00Z" },
      { "action_type": "DELIVERED", "timestamp": "2026-03-13T14:00:00Z" },
      { "action_type": "DISPUTED_DELIVERY", "timestamp": "2026-03-14T08:00:00Z" },
      {
        "action_type": "DISPUTE_RESOLVED",
        "metadata": "Replacement shipped via BlueDart, tracking: BD123456",
        "timestamp": "2026-03-14T10:00:00Z"
      }
    ]
  },
  "timestamp": "2026-03-14T10:00:00Z"
}

Error: No active dispute

{
  "success": false,
  "message": "Cannot resolve dispute. Order must be in DISPUTE_DELIVERY or DISPUTE_QUALITY status. Current status: PAID",
  "data": null,
  "timestamp": "2026-03-14T10:00:00Z"
}

Dispute Timeline Example

Here's a realistic example of an order that goes through a dispute and resolution:

Time	Event	Status	Webhook
Mon 10:00	You create order	`ACCEPTED`	`ORDER_CREATED`
Mon 10:15	Buyer pays	`PAID`	`PAYMENT_SUCCESS`
Mon 14:00	You mark delivered	`DELIVERED`	`DELIVERY_CONFIRMED`
Tue 08:00	Buyer disputes (non-delivery)	`DISPUTE_DELIVERY`	`DISPUTE_RAISED`
Tue 10:00	You resolve dispute	`DELIVERED`	`DISPUTE_RESOLVED`
Wed 10:00	Auto-confirmed (no further dispute)	`COMPLETED`	`ORDER_COMPLETED`