Ir al contenido

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.

Ventana de terminal
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.

Campos opcionales: description (hasta 500 caracteres), external_id (hasta 200) y return_url, que debe ser una URL https://. Una description o un external_id más largos devuelven 400 invalid_description; otro return_url devuelve 400 invalid_return_url. Los depósitos aceptan los mismos campos.

La respuesta es 202 Accepted y ya incluye la address de pago y el payment_url; la factura queda open de inmediato. Guarda su id y dale al pagador el payment_url devuelto. Si la respuesta es 503 address_unavailable, repite la misma solicitud con la misma Idempotency-Key.

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.

Una factura permanece abierta 30 días por defecto. Invoise puede cambiar ese valor, así que envía expires_in si tu integración depende de la vigencia. Para elegir otra vigencia, añade expires_in al cuerpo de la solicitud, por ejemplo "expires_in":"7d". Los valores permitidos son 1h, 2h, 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. Con vigencias cortas como 1h, 2h o 1d, suscríbete a invoice.cancelled para enterarte del vencimiento en el momento.

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

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

Ventana de terminal
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. La dirección llega en la respuesta de creación, igual 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. Invoise cobra su comisión de cada pago, no de cada transferencia entrante: las recargas pagadas juntas pagan una sola comisión, y la comisión mínima de la red se aplica una vez por pago. Una factura paga su comisión una vez, del importe de la factura.

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:

Ventana de terminal
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": "open",
"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": "<option-address>",
"status": "open"
}
],
"expires_at": "2026-10-19T09:00:00Z"
}

Guarda el id del grupo. Cada opción ya trae su address en la respuesta de creación, así que dale al pagador el payment_url del grupo de inmediato; allí elegirá una opción. GET /api/v1/shops/{shop_id}/issuances/{id} devuelve el grupo con todas las opciones.

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.

Por defecto, una factura puede ser de como máximo 1,000,000 tokens. Un comercio puede tener hasta 2,000 facturas activas y hasta 100,000 direcciones de depósito activas en redes EVM, 100,000 en Tron y 100 en Solana, y puede crear por hora como máximo tantas direcciones de pago nuevas como su límite de facturas activas. Cancela las facturas o deshabilita los depósitos que ya no necesites para liberar un lugar. Son valores predeterminados: el personal de Invoise puede fijar otros límites para un comercio. Para atender a más pagadores, deshabilita los depósitos inactivos y vuelve a habilitarlos cuando los necesites: un depósito deshabilitado no cuenta para el límite, y volver a habilitarlo requiere un lugar libre. Una dirección deshabilitada se sigue vigilando, así que el dinero que llegue después se acredita y se paga igualmente. Una dirección de Solana deshabilitada que lleva una hora sin recibir nada se revisa una vez por hora, así que ese dinero aparece con hasta una hora de retraso; no deshabilites una dirección en la que aún esperas un pago. Tú decides qué direcciones cambiar; también puede cambiarlas una clave API de la tienda con write. Consulta Límites para ver los valores exactos y los códigos de error.

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.

Ambas funcionan con una clave de API de la tienda con write o con una sesión de propietario; envía una Idempotency-Key guardada.

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.