n1coePayDocs Referencia del API

Reembolsos

Devuelve el monto completo de un pago desde tu servidor y sigue su resultado con webhooks.

  1. Tu servidor reembolsa un payment intent pagado con POST /v1/refunds.
  2. Revisa el status de la respuesta: succeeded, failed o pending.
  3. Confirma el resultado con los webhooks refund.succeeded y refund.failed.
Reembolsar un pago
curl -s -X POST https://api-epay.dev.n1co.dev/v1/refunds \
  -H "Authorization: Bearer $N1CO_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_intent": "pi_UGF5bWVudEludGVudEV4YW1w",
    "reason": "Duplicate order",
    "metadata": { "ticket": "t-8812" }
  }'
201 Created
{
  "id": "re_UmVmdW5kRXhhbXBsZTAwMDAwMDAx",
  "object": "refund",
  "payment_intent": "pi_UGF5bWVudEludGVudEV4YW1w",
  "amount": 1250,
  "currency": "USD",
  "status": "succeeded",
  "reason": "Duplicate order",
  "metadata": { "ticket": "t-8812" },
  "last_error": null,
  "attempts": 1,
  "created_at": "2026-10-18T10:00:00Z",
  "updated_at": "2026-10-18T10:00:02Z",
  "succeeded_at": "2026-10-18T10:00:02Z",
  "failed_at": null
}

Reglas#

  • Monto completo. No hay reembolsos parciales ni se envía amount.
  • Uno por pago. Repetir el POST reenvía el mismo reembolso o responde un error; nunca crea otro.
  • Solo desde tu servidor. Ni n1co.js ni el comprador ven los reembolsos.
  • El intent sigue succeeded. Su campo refund tiene el id del reembolso.

El resultado#

El llamado espera a n1co hasta unos 45 segundos: usa un timeout de al menos 60.

status Significado
succeeded n1co devolvió el monto. Es final.
failed n1co lo rechazó; last_error dice por qué.
pending Todavía no hay resultado.

Los códigos de last_error y de los errores HTTP están en Errores.

Volver a enviar#

Para reintentar un reembolso failed o pending, repite el POST con el mismo payment_intent. Se reenvía el mismo reembolso y la respuesta es 200.

Si el reembolso se está enviando en ese momento, la respuesta es 409 refund_in_progress con Retry-After.

Resultado desconocido#

Si no se pudo conocer la respuesta de n1co, el reembolso queda pending con outcome_unknown y no hay webhook. Pasados 3 minutos puedes volver a enviarlo.

Leer y recibir el resultado#

GET /v1/refunds/{id} devuelve el reembolso. Los webhooks traen el reembolso en data.object:

Evento Cuándo
refund.succeeded Una vez, cuando n1co devuelve el monto.
refund.failed Por cada envío rechazado.

Los campos del reembolso están en la referencia del API.