Reembolsos

Un reembolso devuelve todo o parte de un pago aprobado. La ruta acepta API key o JWT. Con API key necesitás scope refunds:create y el método del pago debe declarar capability refunds.

Endpoints

POST /v1/payments/{payment_id}/refunds

Crear un reembolso

POST /v1/payments/019f7061-2010-7698-8827-e32f86e14298/refunds
Authorization: Bearer sk_live_7nWm...
Idempotency-Key: order-9821-refund-1
Content-Type: application/json

Idempotency-Key es obligatoria.

Body

amount es requerido. Para un reembolso total, enviá el saldo reembolsable completo.

{
  "amount": {
    "value": "2500.00",
    "currency": "ARS"
  },
  "reason": "Cliente devolvió un ítem"
}

amount.currency debe coincidir con la moneda del pago. amount.value no puede superar el saldo reembolsable (monto del pago menos reembolsos ya aprobados). reason es opcional.

Response

{
  "data": {
    "id": "019f7062-3010-7698-8827-e32f86e14299",
    "payment_id": "019f7061-2010-7698-8827-e32f86e14298",
    "status": "approved",
    "amount": {
      "value": "2500.00",
      "currency": "ARS"
    },
    "reason": "Cliente devolvió un ítem",
    "processor_reference": "rfnd_739204",
    "created_at": "2026-07-17T14:00:00.000Z",
    "updated_at": "2026-07-17T14:00:02.100Z"
  }
}

Efecto sobre el pago

• Reembolso parcial aprobado → el pago pasa a partially_refunded.
• Reembolso que completa el monto → el pago pasa a refunded.

Ejemplo: para un pago de 12500.00 ARS, un primer reembolso aprobado de 2500.00 deja saldo 10000.00 y estado partially_refunded. Un segundo reembolso aprobado de 10000.00 agota el saldo y lleva el pago a refunded. Los reembolsos fallidos o rechazados no reducen el saldo.

Estados del reembolso

created
pending
processing
approved
declined
failed

Errores frecuentes: unsupported_currency, idempotency_key_required, idempotency_key_reused, processor_timeout, processor_unavailable, connector_configuration_invalid.

Resultado incierto

Ante un timeout, no crees otro reembolso con una key nueva. Repetí el mismo request con la misma Idempotency-Key o reconciliá el pago. El procesador podría haber aplicado la devolución aunque PagoFast no haya recibido una respuesta concluyente.

Webhooks

Un reembolso aprobado actualiza el pago y puede producir payment.refunded. Para reembolsos parciales, el estado del pago puede aparecer como partially_refunded dentro del payload aunque no exista un tipo de evento separado. Tomá el estado del recurso como fuente de verdad y deduplicá por ID de evento.