Skip to main content
Cuando necesitas devolverle la plata a un tarjetahabiente —un pedido cancelado, un cargo duplicado, un reclamo resuelto a favor del cliente— la devolución es una operación de tu cuenta: el procesador le devuelve el dinero a la tarjeta y nosotros debitamos ese mismo valor de tu saldo, con su asiento en la cartola, su comprobante verificable y su webhook. Es lo contrario de un cobro: el cobro acredita, la devolución debita.

​
Qué se puede devolver

Los cobros por QR, transferencia anunciada, cuenta de depósito dedicada y collect no se devuelven por este camino (refund_not_supported): esos rieles no tienen capacidad de devolución en el procesador. Los cobros POS se devuelven por el riel crypto con POST /v1/pos/charges/{id}/refunds.
La comisión y el margen de cambio no se reembolsan. Se debita de tu saldo el valor que el cobro trajo (bruto), no el neto que se acreditó: si cobraste 100.00 USD y te acreditamos 97.10 USDT después de una comisión de 2.90, devolver el total debita 100.000000 USDT. La diferencia la pones tú, igual que en cualquier procesador de tarjetas.

​
Ciclo de vida

Un 202 pending no es un error: la devolución puede estar hecha. Si reintentas con una idempotency_key distinta, el pagador recibe la plata dos veces. Reintenta siempre con la misma clave (te devolvemos el objeto original) o espera el webhook.

​
Pedir una devolución

1

Devuelve el total del cobro

Omite amount para devolver todo lo que queda por devolver:
La respuesta es 201 cuando el procesador aprueba en el acto, 202 cuando queda en curso y 422 cuando rechaza.
2

O devuelve una parte

Manda amount en la moneda del cobro (no en USDT). El débito se calcula proporcional al valor que ese cobro trajo:
Puedes pedir varias parciales del mismo cobro. Cuando la suma supera lo que queda por devolver, respondemos 422 refund_exceeds_payin sin tocar tu saldo.
3

Anula en vez de devolver (mismo día)

Si el cobro todavía no se liquidó en el procesador, kind: "void" lo anula en vez de generar una devolución. Para tu saldo el efecto es el mismo; para el tarjetahabiente, la anulación suele reflejarse antes en su estado de cuenta.
Si el cobro ya no admite anulación, el procesador la rechaza y puedes pedir la devolución normal.
4

Consulta el estado

Y el historial de un cobro:

​
Segundo factor

POST /v1/payins/{payinID}/refunds es una operación que saca plata de tu cuenta, así que exige segundo factor cuando la origina una persona con su sesión (acción payin_refund). Si tu organización lo tiene activo, la primera llamada responde 403 otp_required con un challenge_id: verifica el código y repite el request con el token del desafío. Las API keys están exentas por diseño, igual que en el resto de la plataforma: tu backend integra sin fricción.

​
Historial y filtros

Filtros: status (pending, completed, failed), kind (refund, void, chargeback), payin_id, from/to y paginación.

​
Cuánto lleva devuelto cada cobro

Cada cobro expone su avance de devolución, y puedes filtrar el listado de cobros por él:
El cobro no cambia de estado: sigue credited. Tu historial financiero no se reescribe; la devolución es un movimiento nuevo.

​
Contracargos

Cuando el emisor de la tarjeta impone un contracargo (chargeback), la plata ya salió: no es una decisión tuya ni nuestra. En ese caso:
  • Debitamos el monto de tu saldo automáticamente, con kind: "chargeback".
  • El débito se aplica aunque no tengas saldo: la cuenta puede quedar en negativo y esa deuda se descuenta de tus próximos abonos.
  • Recibes el webhook payin_refunded con kind: "chargeback" y, si el saldo quedó negativo, el campo balance_after.
Un contracargo no se pide por API: llega desde el emisor. Lo único que puedes hacer es verlo en tu cartola, tu historial y tu comprobante.
Lo debitado entre devoluciones y contracargos de un mismo cobro nunca supera lo que ese cobro trajo. Si un contracargo llega después de que ya devolviste, el débito se acota a lo que quedaba —o queda en cero, con la razón registrada— para que nunca te cobremos dos veces el mismo dinero.

​
Webhook payin_refunded

Se emite en cada estado final (completed o failed) y en el contracargo. Los pending no emiten: espera el final.
En un rechazo llega además failure_reason; en un contracargo que deja la cuenta en negativo, balance_after.

​
Comprobante

Cada devolución tiene su comprobante PDF con la marca de tu organización y un código de verificación pública:
Cualquiera puede validar ese código en la página pública de verificación, sin credenciales y sin ver datos personales. Detalle en Comprobantes.

​
Errores

Catálogo completo en Errores.

​
Preguntas frecuentes

No. La comisión y el margen de cambio del cobro original no se reembolsan: se debita el valor bruto que el cobro trajo y la casa retiene lo que cobró. Es el comportamiento estándar de la industria de tarjetas.
No con otra clave. Un 202 significa que la devolución puede haberse ejecutado y todavía no tenemos confirmación. Reintentar con una clave nueva sería una segunda devolución real. Repite el request con la misma idempotency_key (te devolvemos el mismo objeto) o espera el webhook payin_refunded.
Siempre en USDT, la moneda en que se acreditó el cobro, aunque tu cuenta tenga configurado otro saldo predeterminado para los payins. No convertimos por tu cuenta: si no tienes USDT suficiente, respondemos insufficient_funds.
Mientras el cobro esté credited y le quede saldo por devolver, sí por nuestra parte. El límite real lo pone el procesador y las reglas de las marcas (habitualmente 180 días); pasado ese plazo la devolución se rechaza con failed y el monto reservado vuelve a tu saldo intacto.
La cuenta puede operar en negativo solo por esta causa. La deuda se salda automáticamente con tus próximos abonos; mientras tanto, las operaciones que sacan plata seguirán exigiendo saldo disponible.
Sí. El panel de administración permite originar la devolución sobre cualquier cuenta de la organización; queda auditada con el administrador que la ejecutó y aparece en tu historial con requested_by: "admin".
Última modificación el 10 de agosto de 2026