Disputes (chargebacks)

A dispute happens when a customer asks their card issuer, their bank or the payment method's provider to reverse a payment — every payment method can be disputed (see by payment method). VezmoPay records every dispute on your payments, tells you in real time, and lets you respond — always with your VezmoPay ids, never a processor's.

There are two kinds:

• Chargeback (needs_response and onward) — a formal dispute. The disputed amount is taken from your balance until it is decided (a bank dispute usually arrives already decided).
• Inquiry (warning_* statuses) — the customer's card issuer or bank asks a question before (or instead of) a chargeback. No funds are held and no dispute fee is charged. Answer it quickly: an unanswered inquiry usually becomes a chargeback.

What happens to the money

• When a dispute opens (for a bank payment, usually when it arrives already decided — see by payment method), the disputed amount is taken from your balance and your account's dispute fee is charged — you can see it in your dashboard under VezmoPay → Settings → Fees. It is charged once per dispute and is not returned if you win. An inquiry is charged only if it becomes a chargeback.
• When evidence is submitted to fight a chargeback (including a saved draft, which is sent automatically before the deadline), your account's dispute response fee is charged, once per dispute. It is listed under VezmoPay → Settings → Fees and refunded if you win. Answering an inquiry costs nothing.
• Won — the held amount returns to your balance, and so does the response fee.
• Lost — the held amount goes to the customer. Nothing more is charged at that point. A partly won dispute counts as lost here: the response fee is not refunded.
• The amount can be less than the payment (a partial dispute). Always use the dispute's own amount.
• The payment itself does not change: it was paid, so GET /merchant/payment/:id keeps its state (e.g. succeeded) and gains a dispute block. No payment.* webhook fires for a dispute — the dispute.* events are the signal.

By payment method

Every payment method can be disputed, but not the same way. Each dispute tells you which one in paymentMethod.

A bank payment that comes back for any other reason (insufficient funds, a closed account) is not a dispute: it arrives as payment.failed with the return reason. See Bank payments.

How to respond

Disputes are answered from your dashboard, not the API: evidence is mostly files (receipts, delivery proof, correspondence). Go to VezmoPay → Disputes, open the dispute, and either:

• Submit evidence — a guided 2-step wizard (product or service details, customer communication, refund policy, delivery proof and file uploads). Submit before evidenceDueBy; a dispute with no response by then is lost.
• Accept the dispute — concede it (the amount stays with the cardholder and the fee is not returned) instead of spending effort on a case you can't win.

Our team can also file evidence on your behalf when you raise it through your To-Do requests.

Webhooks

Subscribe to these in VezmoPay → Developers → Webhooks. Every delivery is signed and retried like any other event (see Webhooks).

An event fires only when the status actually changes, so a dispute never sends the same status twice. All three events carry the same data:

{
  "id": "evt_…",                          // unique per event: one id per status change
  "event": "dispute.created",
  "data": {
    "id": "cmd8x2k1p0001ab12cdef3456",    // the VezmoPay dispute id
    "paymentId": "cmd7q9w0e0003xy98zyxw7654", // GET /merchant/payment/:id
    "transactionId": "VTQ4Z3E6",          // the payment's VezmoPay reference
    "paymentMethod": "card",              // card | ach | instantAch | cashapp | …
    "amount": 357,                        // major units: 357 = $357.00
    "currency": "USD",
    "reason": "fraudulent",
    "reasonCode": "10.4",                 // the card network's code, or null
    "status": "needs_response",
    "evidenceDueBy": "2026-10-20T23:59:59.000Z", // respond before this; null if none
    "livemode": true,                     // false for a Test-mode dispute
    "createdAt": "2026-10-08T14:03:11.000Z",     // when the dispute was opened
    "companyId": "…",
    "userId": "…",                        // the payment's owner, or null
    "merchantId": "VZM…",                 // your VezmoPay merchant id
    "type": "vezmopay"
  }
}

Idempotency: the envelope id is unique per event and stays the same across retries of that event — dedupe on it (or on data.id + data.status).

Amounts in every event (payments, refunds, payouts, disputes) are the same: major units, as a JSON number.

Statuses

Read disputes with the API

For reconciliation, or to catch up after missed webhooks. Same token as the payment API (see Authentication) and the payment.read scope. A Test key sees sandbox disputes and a live key sees live ones. Each item is the same object as the webhook's data (without companyId, userId, merchantId and type).

List — GET /merchant/dispute

Newest first. Optional query parameters:

• status — comma-separated statuses, or open (still being decided) / closed (final).
• paymentId — only disputes on this payment.
• from / to — opened on or after / on or before (YYYY-MM-DD or ISO 8601; a bare date covers the whole day).
• page (default 1), limit (default 20, max 100).

curl "https://api.vezmo.com/api/v1/merchant/dispute?status=open&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "success": true,
  "message": "Disputes retrieved",
  "data": {
    "data": [
      {
        "id": "cmd8x2k1p0001ab12cdef3456",
        "paymentId": "cmd7q9w0e0003xy98zyxw7654",
        "transactionId": "VTQ4Z3E6",
        "paymentMethod": "card",
        "amount": 357,
        "currency": "USD",
        "reason": "fraudulent",
        "reasonCode": "10.4",
        "status": "needs_response",
        "evidenceDueBy": "2026-10-20T23:59:59.000Z",
        "livemode": true,
        "createdAt": "2026-10-08T14:03:11.000Z"
      }
    ],
    "pagination": { "total": 1, "page": 1, "limit": 50, "totalPages": 1, "nextPage": null, "prevPage": null }
  }
}

Retrieve — GET /merchant/dispute/:id

One dispute by its id. 404 for an unknown id, another merchant's, or one from the other mode (Test vs live).

curl https://api.vezmo.com/api/v1/merchant/dispute/cmd8x2k1p0001ab12cdef3456 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

On the payment

GET /merchant/payment/:id and the payment list carry a dispute block with the payment's newest dispute (id, status, amount, currency, reason, evidenceDueBy), or null.

Test disputes in sandbox

1. Use your Test API key and a sandbox checkout.
2. Pay with card 4000 0000 0000 0259 (any future expiry, any CVC). The payment succeeds, then is disputed as fraudulent.
3. Your endpoint receives dispute.created with livemode: false, and GET /merchant/dispute with the Test key lists it. It usually arrives within seconds; allow up to 10 minutes.
4. Submit evidence on it from the dashboard (in Test mode) to receive dispute.updated (under_review).

To test a bank (ACH) dispute, pay by bank in a sandbox checkout with routing number 110000000 and account number 000555555559. The payment succeeds and is then disputed; you receive dispute.created and dispute.closed with status: "lost" and paymentMethod: "ach".

Test and live events go to the same endpoint — always check livemode. Sandbox disputes move no money and charge no fee.

Reduce disputes

• Use a clear statement descriptor so customers recognize the charge on their statement.
• Refund questionable payments early — a refund costs less than a lost dispute, which also carries the fee and counts toward your dispute rate.
• Answer inquiries: most chargebacks that follow an inquiry follow one that went unanswered.
• If enabled, VezmoPay's pre-dispute alerts can refund flagged payments before they become chargebacks — ask us to turn on Pre-Dispute Protection.