Depósitos y facturas

Usa una factura para un pedido único con un precio fijo. Usa un depósito para un saldo de cliente que se puede recargar repetidamente.

Crea una factura

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"amount\":\"${AMOUNT:?}\",\"external_id\":\"order-123\"}"

Sustituye {shop_id} por el ID de tu tienda. Define CHAIN_ID y TOKEN_ADDRESS a partir de la respuesta de la API y AMOUNT en las unidades más pequeñas del token elegido. external_id vincula la factura a un pedido de tu sistema; no sustituye a la clave de idempotencia.

La respuesta es 202 Accepted. Guarda su id y sondea el endpoint de la operación hasta que address esté disponible. Luego dale al pagador el payment_url devuelto.

Los pagos parciales se suman. En cuanto llega suficiente dinero confirmado, Invoise programa el pago y cierra la factura. El destinatario recibe el importe de la factura menos la comisión del servicio. Cualquier pago en exceso va a Invoise, no al destinatario.

Las facturas son pagos únicos; no se renuevan automáticamente.

Vigencia de la factura

Una factura permanece abierta 30 días por defecto. Para elegir otra vigencia, añade expires_in al cuerpo de la solicitud, por ejemplo "expires_in":"7d". Los valores permitidos son 1d, 7d, 30d, 180d y 365d.

Las respuestas de factura, incluida la página de pago pública, incluyen expires_at. Cuando pasa ese momento, una factura sin pagar se cierra: se define cancelled_at y se envía el webhook invoice.cancelled con data.reason establecido en expired. Un pago que llega después sigue registrándose y aún puede liquidarse, como con una factura cancelada.

Los depósitos no caducan. Enviar expires_in al crear un depósito devuelve 400 invalid_expires_in.

Crea una dirección de depósito

Usa las mismas cabeceras de solicitud con este endpoint y cuerpo:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/deposits' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d "{\"chain_id\":${CHAIN_ID:?},\"token\":\"${TOKEN_ADDRESS:?}\",\"external_id\":\"customer-123\"}"

No definas un amount fijo. Espera la dirección de la misma forma que con una factura. La dirección puede recibir recargas repetidas en el token y la red elegidos.

Los depósitos pequeños se acumulan hasta alcanzar el umbral de pago de la tienda. Consúltalo en GET /api/v1/shops/{shop_id}/terms.

Ofrece varios tokens o redes

Envía assets en lugar de chain_id y token para dejar que el pagador elija cómo pagar. Funciona tanto para facturas como para depósitos:

curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/invoices' \
  -H 'Authorization: Bearer ivk_...' \
  -H 'Idempotency-Key: <saved-unique-key>' \
  -H 'Content-Type: application/json' \
  -d '{"assets":[{"chain_id":<chain-id>,"token":"<token-address>"},{"chain_id":<other-chain-id>,"token":"<other-token-address>"}],"amount":"10.5","external_id":"order-124"}'

Con assets, el amount de la factura es un importe de token con decimales, como "10.5", no unidades base: los tokens pueden tener decimales distintos. Cada opción debe alcanzar el minimum_payment de su red.

La respuesta es un grupo. Cada opción es una factura o dirección de depósito independiente con su propio address, importe en unidades base y estado:

{
  "id": "<group-id>",
  "group": true,
  "shop_id": "<shop-id>",
  "public_id": "<public-id>",
  "status": "registering",
  "payment_url": "https://pay.invoise.me/<public-id>",
  "options": [
    {
      "id": "<option-id>",
      "public_id": "<option-public-id>",
      "chain_id": 12345,
      "token": "<token-address>",
      "token_decimals": 6,
      "family": "evm",
      "amount": "10500000",
      "address": null,
      "status": "registering"
    }
  ],
  "expires_at": "2026-10-19T09:00:00Z"
}

Guarda el id del grupo. GET /api/v1/shops/{shop_id}/issuances/{id} devuelve el grupo con todas las opciones; sondéalo hasta que las opciones tengan direcciones, y luego dale al pagador el payment_url del grupo, donde elegirá una opción.

Un grupo de facturas se paga una sola vez. Su status sigue a la opción que se pagó, y paid_issuance_id la identifica. Los eventos de webhook se envían por opción e incluyen group_id y group_public_id. duplicate: true significa que el grupo ya se pagó mediante otra opción: no acredites el pedido dos veces. Un grupo de depósitos mantiene una dirección reutilizable por opción.

Cancela un grupo de facturas o pausa un grupo de depósitos mediante el id del grupo; todas las opciones cambian juntas. El id propio de una opción devuelve 400 issuance_in_group.

Si una opción no se puede crear, no se crea nada y error.details identifica la opción como {chain_id, token}. Un par vacío o repetido, o assets enviado junto con chain_id o token, devuelve 400 invalid_assets.

Límites

Una factura puede ser de como máximo 1,000,000 tokens. Un comercio puede tener hasta 2,000 facturas activas y un número limitado de direcciones de depósito activas por familia de red. Cancela las facturas o deshabilita los depósitos que ya no necesites para liberar un lugar. Consulta Límites para ver los valores exactos y los códigos de error.

Pausa un depósito o cancela una factura

Acción	Solicitud
Pausar la página de pago de un depósito	PATCH /api/v1/shops/{shop_id}/deposits/{id} con {"enabled":false}. Usa true para habilitarla de nuevo.
Cancelar la página de pago de una factura	POST /api/v1/shops/{shop_id}/invoices/{id}/cancel.

Envía autenticación y una Idempotency-Key guardada para cualquiera de las dos operaciones.

Estas acciones cierran la página de pago. No reembolsan el dinero ni detienen el monitoreo de la dirección. Los fondos enviados a una factura cancelada todavía pueden liquidarse; sus eventos incluyen invoice_cancelled: true.

Los fondos enviados después de que una factura ya se haya liquidado se registran como transferencias tardías. No se pagan automáticamente. La recuperación, incluida la recuperación de token incorrecto, requiere una operación manual independiente.

Consulta la referencia de la API para ver todos los campos de solicitud y respuesta.