Payment disputes - Zahlo Merchant Developer Docs

A dispute reverses or challenges a payment. Treat it as an operational workflow with a due date, evidence record, and final outcome. Keep customer communication and order records linked to the payment ID.

Monitor disputes

List disputes from a scheduled server job and alert the team responsible for the affected order.

const response = await fetch("https://merchant.zahlo.eu/api/v1/disputes?limit=50&offset=0", {
  headers: { "x-api-key": process.env.ZAHLO_API_KEY },
});
const { data } = await response.json();
for (const dispute of data) await notifyDisputeOwner(dispute);

Do not expose evidence URLs, customer data, or dispute details to unauthorized users. Reconcile the dispute status with the payment and any refund before changing an order or entitlement.

Submit evidence

Collect only relevant evidence, validate that it belongs to the payment, and submit it with an idempotency key. Use controlled HTTPS URLs or the documented upload flow; do not place secrets in evidence.

curl -X POST "https://merchant.zahlo.eu/api/v1/disputes/dp_demo_1001/respond" \
  -H "x-api-key: ${ZAHLO_API_KEY}" \
  -H "Idempotency-Key: dispute-dp_demo_1001" \
  -H "Content-Type: application/json" \
  -d '{"evidence":{"customerCommunication":"https://store.example/evidence/order_1001"},"submit":true}'

Record submission time and response status. A submitted response is not a guaranteed win; continue processing final dispute events.