Estado de facturas y depósitos

Consulta el estado de la factura o el depósito mediante solicitudes GET. Los webhooks te notifican los cambios automáticamente.

Consulta una factura o depósito

Usa el id que se devolvió al crear la factura o el depósito:

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'

Campos relevantes de una respuesta de ejemplo (se omiten otros campos):

{
  "id": "f06b8a31-19c7-4687-ade3-1c09466d2751",
  "kind": "invoice",
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "token_decimals": 6,
  "expires_at": "2026-10-19T10:00:00Z",
  "cancelled_at": null,
  "disabled_at": null,
  "payout_tx_hash": null
}

Ambos importes son cadenas de enteros en unidades base. Este ejemplo significa que llegaron 10 tokens, pero todavía no se muestra ninguna transacción de pago confirmada.

Interpreta una factura

status	Qué hacer
registering	Espera a que address no esté vacío. No la derives tú mismo.
open	Sigue esperando. received puede mostrar un pago parcial.
funded	Hay fondos confirmados suficientes disponibles para la liquidación.
settled	La factura se cerró en la cadena.
reconciling	Espera la reconciliación; no lo trates como un pago exitoso.

Comprueba también cancelled_at. Es una marca de tiempo o null, no un valor de estado. Se define cuando cancelas la factura, cuando una factura sin pagar supera su expires_at, o cuando el personal de Invoise bloquea el comercio; el webhook invoice.cancelled distingue estos casos mediante data.reason. La cancelación oculta la página de pago pero no detiene los fondos entrantes ni la liquidación. Decide explícitamente cómo gestiona tu negocio una factura pagada y cancelada.

funded significa que se recibió el pago, no que el pago al destinatario se completó. settled registra el cierre de la factura. Para la contabilidad completa del pago, usa payout.confirmed; payout_tx_hash identifica la última transferencia saliente confirmada al destinatario, cuando está disponible.

Si recibes transfer.reverted, Invoise está informando de la reversión de una transferencia entrante concreta en la red. Identifícala mediante chain_event.reference_event_id, consulta el estado actual de la factura y ajusta tu registro de esa transferencia una sola vez. Consulta Webhooks para ver el formato del evento.

Sigue los depósitos

Una dirección de depósito es reutilizable. Puede volver a open después de un pago, así que no esperes a que quede en settled de forma permanente.

received es el dinero entrante confirmado acumulado, no el saldo restante. Un pago no se resta de él. Puede disminuir cuando se revierte una transferencia. Acredita cada pago entrante una sola vez; los webhooks son útiles para esto porque cada evento tiene un ID estable.

disabled_at controla la disponibilidad de la página de pago. Deshabilitar un depósito no detiene el monitoreo de su dirección.

Lista facturas y depósitos

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
  -H 'Authorization: Bearer ivk_...'

Con limit (1–100), la respuesta es {"items":[...],"next_cursor":"..."}. Envía cursor para la página siguiente hasta que next_cursor esté vacío. Sin parámetros de paginación, el endpoint devuelve un array limitado; no es el historial completo.

La lista admite los filtros kind, status y q. Su filtro status=paid selecciona funded y settled; paid no es un estado de operación devuelto por el endpoint de detalle.

El campo transfers del endpoint de detalle contiene solo las diez entradas confirmadas más recientes de entrada/pago. No lo uses como un libro contable completo.

Estado público de la página de pago

GET /api/v1/checkout/{public_id} no necesita credenciales. Proporciona el estado de la página de pago, incluidos status, received, amount y expires_at. Usa el endpoint de operación autenticado para los registros de tienda de tu backend.

Para actualizaciones push y comprobación de firma, consulta Webhooks.