Copy page

Plataforma

Reembolsos

La API de Reembolsos permite a los comercios devolver fondos a un pagador después de que una solicitud de pago alcance un estado reembolsable. Los reembolsos están limitados a la organización o cuenta que posee el punto de venta de la solicitud de pago.

Resumen

Cuando creas un reembolso, Fluxis:

1. Valida que tus credenciales API puedan acceder al POS de la solicitud de pago
2. Comprueba que la solicitud de pago esté en un estado elegible
3. Crea un registro de reembolso en estado processing
4. Envía un webhook refund (si está configurado) con el estado inicial

Estados elegibles de solicitud de pago

Los reembolsos solo pueden crearse cuando la solicitud de pago está en uno de estos estados:

Estado	Uso típico
completed	Pago completo recibido; reembolsar el monto pagado
overpaid	El pagador envió más de lo solicitado
underpaid	El pagador envió menos de lo solicitado
confirmed	Transacción de libro creada después del pago

Las solicitudes en pending, created, processing, expired o failed no son elegibles.

Autenticación

Todos los endpoints de reembolso requieren ambos encabezados:

• Authorization: Bearer <access_token>
• x-fluxis-api-key: <your_api_key>

Consulta Autenticación y configuración para el intercambio de tokens.

Crear un reembolso

Code
POST /v1/refunds/payment-request/{paymentRequestID}

Cuerpo de la solicitud

Campo	Requerido	Descripción
refund_to_address	Sí	Dirección blockchain que recibirá el reembolso
amount	No	Cadena decimal. Si se omite, usa el monto registrado de la solicitud de pago
reason	No	Motivo en texto libre para auditoría

Ejemplo

Code
curl -X POST "https://api.fluxis.us/v1/refunds/payment-request/aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-fluxis-api-key: fxs.prd.YOUR_KEY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "50.00",
    "reason": "Customer overpaid"
  }'

Respuesta (200)

Code
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "refund_to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "50.00",
    "status": "processing"
  }
}

Obtener detalles del reembolso

Code
GET /v1/refunds/{refundID}

Devuelve metadatos completos del reembolso incluyendo red, activo, hash de la transacción de pago original y refund_transaction_hash una vez que se complete el procesamiento on-chain.

Campo	Descripción
status	processing, completed o failed
payment_transaction_hash	Hash del pago entrante original
refund_transaction_hash	Hash del reembolso saliente (presente tras ejecución on-chain)
unique_asset_id	Identificador de activo (p. ej. Polygon USDC)
network	Red blockchain del reembolso

Solo puedes recuperar reembolsos creados por la misma entidad autenticada (organización o cuenta).

Estados de reembolso

Estado	Significado
processing	Registro de reembolso creado; transferencia on-chain pendiente
completed	Transacción de reembolso confirmada on-chain
failed	El reembolso no pudo completarse

Hoy, los reembolsos recién creados permanecen en processing hasta que se implemente la ejecución on-chain.

Webhooks

Registra un webhook con event_type: "refund" a nivel de cuenta. Al crear, Fluxis envía:

Code
{
  "data": {
    "notification_type": "refund_status_update",
    "refund_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "status": "processing",
    "amount": "50.00"
  }
}

Verifica cada entrega usando Verificación de firma de webhook. Consulta Eventos de webhook para el catálogo completo de eventos.

Errores comunes

HTTP	Causa
400	ID de solicitud de pago inválido, monto o estado de solicitud no elegible
403	Las credenciales API carecen de permiso para el POS de la solicitud de pago
404	Reembolso no encontrado (solo GET)

Documentación relacionada

• Solicitudes de pago — ciclo de vida y estados límite
• Eventos de webhook — payload del evento refund
• Transacciones — registros de libro tras confirmación de pago