Disputas

Las disputas (dispute, o chargeback) son reclamos que abre el titular de una tarjeta sobre una venta. Como la venta es tuya, la disputa también: si se pierde (o la aceptas), el monto disputado y una fee de USD 15 se descuentan de tu saldo. Desde vexorpay puedes listarlas, verlas y aceptarlas; por ahora no se puede enviar evidencia. Las disputas llegan solas: se dispara el webhook dispute.created cuando se abre y dispute.updated con cada cambio.

Listar disputas

GET /api/v1/disputes

Parámetros

Ejemplo

curl "https://api.vexorpay.com/api/v1/disputes?status=needs_response" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Respuesta exitosa

200 OK

{
  "data": [
    {
      "id": "68f1c1e2c8a4b0d1f2e3a4b5",
      "orderId": "67f1c1e2c8a4b0d1f2e3a4b5",
      "paymentLinkId": "66f1c1e2c8a4b0d1f2e3a4b5",
      "paymentLinkUrl": "https://www.vexorpay.com/p/a1b2c3d4e5",
      "reference": "ORD-1001",
      "customerEmail": "cliente@mail.com",
      "status": "needs_response",
      "statusLabel": "Requiere respuesta",
      "reason": "fraudulent",
      "reasonLabel": "Fraude",
      "amountCents": 1900,
      "currency": "usd",
      "feeCents": 1500,
      "evidenceDeadline": "2026-10-15T12:00:00.000Z",
      "daysLeft": 7,
      "isOpen": true,
      "canAccept": true,
      "outcome": null,
      "sandbox": false,
      "createdAt": "2026-10-08T12:03:00.000Z",
      "resolvedAt": null
    }
  ],
  "has_more": false,
  "total_count": 1,
  "url": "/v1/disputes?limit=10"
}

Campos clave:

• status: abiertas: warning_needs_response y warning_under_review (alerta previa a la disputa), needs_response y under_review. Cerradas: warning_closed, won, lost y closed. statusLabel es el estado en texto.
• orderId: la venta disputada (GET /api/v1/orders/{id}).
• amountCents: el monto disputado.
• feeCents: la fee de la disputa (USD 15), que se descuenta de tu saldo.
• canAccept: si se puede aceptar (dar por perdida). Es true en needs_response y warning_needs_response.
• evidenceDeadline / daysLeft: plazo de respuesta (null cuando no aplica).
• outcome: won o lost cuando se resuelve; null mientras está abierta.

Obtener una disputa

GET /api/v1/disputes/{id}

El entorno lo define la API key: con una clave vxp_test_... operas sobre disputas de prueba. Devuelve el mismo objeto de la lista o 404 dispute_not_found.

Aceptar una disputa

POST /api/v1/disputes/{id}/accept

La das por perdida: el monto disputado no vuelve. Es irreversible. Es la única acción posible sobre una disputa. Devuelve la disputa actualizada. Con un token OAuth exige el scope disputes:write.

curl -X POST https://api.vexorpay.com/api/v1/disputes/68f1c1e2c8a4b0d1f2e3a4b5/accept \
  -H "Authorization: Bearer vxp_live_tu_clave"

Errores