Devoluciones (refunds)

Una devolución se pide sobre un payment autorizado (pay_…, lo encuentras en GET /v1/payment-intents/{id} → payment.id). Puede ser parcial o total, y como toda operación que mueve dinero, es idempotente.

curl -s -X POST "$BASE/v1/payments/pay_01…/refunds" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 10000, "external_reference": "refund-001" }'

{
  "id": "ref_01…",
  "payment_id": "pay_01…",
  "amount": 10000,
  "currency": "CLP",
  "status": "SUCCEEDED",
  "external_reference": "refund-001",
  "payment_intent_status": "PARTIALLY_REFUNDED",
  "created_at": "…"
}

Reglas

Regla	Si no se cumple
El intent está `AUTHORIZED` o `PARTIALLY_REFUNDED`	`409 PAYMENT_INVALID_STATE`
`amount` es un entero mayor que cero	`400 VALIDATION_ERROR`
La suma de devoluciones no supera el monto autorizado	`422 REFUND_AMOUNT_INVALID`
El `Idempotency-Key` ya se usó con otro body	`409 IDEMPOTENCY_CONFLICT`

Cuando la suma de devoluciones alcanza el monto autorizado, el intent pasa a REFUNDED; antes de eso, a PARTIALLY_REFUNDED.
Una devolución que el proveedor rechaza queda con status: "FAILED", no cuenta para el tope y genera refund.failed.
external_reference es opcional y te sirve para enlazar la devolución con tu sistema (por ejemplo, la nota de crédito).

Reglas​

Reglas