Integración por API
Acepta pagos con criptomonedas desde billeteras cripto externas mediante la Merchant API.
Con la integración por API, tu aplicación crea facturas cripto, muestra las instrucciones de pago a los clientes y sigue el estado del pago mediante la API o las notificaciones a la Status URL.
Puedes usar la API de tres formas:
-
Solo API con consulta del estado: tu aplicación crea toda la experiencia de pago y consulta el estado del pago mediante la API.
-
Solo API con notificaciones a la Status URL: tu aplicación crea toda la experiencia de pago, y una configuración de Hosted Checkout aporta la Status URL que recibe las notificaciones de pago. La página de Hosted Checkout no se usa.
-
API + Hosted Checkout: tu backend usa la API para el seguimiento y la conciliación de pedidos, mientras Hosted Checkout ofrece la página de pago para el cliente.
Cuándo usar la integración por API
Usa la integración por API cuando quieras controlar el flujo de pago en tu propio sitio web, aplicación, bot o agente de IA.
La integración por API es útil cuando:
- Quieres crear tu propia interfaz de checkout.
- Necesitas crear facturas cripto de forma programática.
- Quieres mostrar las instrucciones de pago dentro de tu propio producto.
- Necesitas seguir el estado del pago desde tu backend.
- Quieres recibir notificaciones del estado de los pagos en tu servidor.
- Quieres combinar Hosted Checkout con la conciliación de pedidos en el backend.
Si quieres la integración más rápida con una página de pago lista para usar, usa la integración de Hosted Checkout.
Modelos de integración
| Modelo | Experiencia del cliente | Responsabilidad del backend | Gestión del estado |
|---|---|---|---|
| Solo API + consulta | Creada por tu aplicación | Crear la factura, mostrar los datos de pago, seguir el estado | Consultar GET /api/orders |
| Solo API + Status URL | Creada por tu aplicación | Crear la factura, mostrar los datos de pago, procesar las notificaciones | Status URL de Hosted Checkout, con consulta por API para la conciliación |
| API + Hosted Checkout | Alojada por Volet.com | Seguir pedidos y conciliar el estado del pago | Status URL de Hosted Checkout, con consulta por API para la conciliación |
Antes de empezar
Para aceptar pagos cripto mediante la API, necesitas:
- Una cuenta de Volet.com verificada.
- Una API configurada en la sección Herramientas de pago.
- Los siguientes permisos de API:
- Realizar transacciones → Aceptar pagos cripto: para crear facturas cripto.
- Buscar transacción: para obtener los pedidos de pago.
- Una configuración de Hosted Checkout cuyo nombre puedas enviar como
sciName.
Consulta Crear una pasarela de pago para crear y configurar tu API y Hosted Checkout.
sciNameLa implementación actual de GET /api/orders exige el nombre de un Hosted Checkout (sciName) para obtener un pedido.
Mientras se mantenga este requisito, crea una configuración de Hosted Checkout y envía su nombre como sciName al crear las facturas cripto que necesites seguir.
No hace falta redirigir a los clientes a la página de Hosted Checkout. La configuración puede servir solo para aportar el sciName necesario y, opcionalmente, las notificaciones a la Status URL.
Autenticación
Las solicitudes a la Merchant API requieren encabezados de autenticación.
Incluye los siguientes encabezados en cada solicitud a la API:
| Encabezado | Descripción |
|---|---|
Api-Name | Nombre de la API configurado en tu cuenta de Volet.com. |
Account-Email | Email de la cuenta de Volet.com a la que pertenece la API. |
Authentication-Token | Token SHA-256 generado a partir de password:YYYYMMDD:HH (UTC), donde la contraseña es la que configuraste en tu cuenta de Volet.com, en Herramientas de pago. |
Por ejemplo:
SHA256("MySecret123:20261026:14")
da como resultado:
c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd
El valor del token cambia cada hora UTC. Genera un token nuevo justo antes de cada solicitud para no reutilizar un token generado en la hora anterior.
A la API solo se envía el token generado. Nunca envíes la contraseña de tu API.
Mantén en privado la contraseña de tu API. Nunca expongas las credenciales de la API ni los tokens de autenticación en código frontend, apps móviles, bots o scripts del lado del cliente.
Ejemplo de solicitud autenticada:
curl -X POST https://api.volet.com/api/invoice/crypto-invoice/deposit \
-H "Content-Type: application/json" \
-H "Api-Name: my-store-api" \
-H "Authentication-Token: c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd" \
-d '{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"sciName": "Store",
"orderId": "ORDER-1001"
}'
Flujo de pago solo con API
Usa este flujo cuando tu aplicación gestiona toda la experiencia de pago cripto.
- Crea un pedido en tu sistema.
- Opcionalmente, verifica los datos calculados de la factura.
- Crea una factura cripto mediante la API.
- Muestra al cliente la dirección de pago, el monto, la moneda, la red y el plazo de vencimiento.
- El cliente envía el pago desde una billetera cripto.
- Sigue el pago con
GET /api/orders, con las notificaciones a la Status URL o con ambos. - Cuando el pago se completa, actualiza el estado del pedido en tu sistema.
Paso 1 (opcional): verificar los datos de la factura
Antes de crear una factura, puedes verificar los valores calculados.
Usa este paso para ver de antemano el monto del remitente, el monto del destinatario, la conversión de moneda y el plazo de vencimiento antes de crear la factura real.
Endpoint:
POST /api/invoice/crypto-invoice/check
Consulta Verificar factura cripto en la referencia de la API.
Ejemplo de solicitud:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com"
}
Ejemplo de respuesta:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com",
"senderAmount": 100,
"receiverAmount": 100,
"expirationDate": "2026-01-15T10:30:00",
"expirationDateMillis": 1768473000000
}
Este paso no crea una dirección de pago ni inicia el pago.
Paso 2: crear una factura cripto
Crea una factura cripto cuando el cliente esté listo para pagar.
Endpoint:
POST /api/invoice/crypto-invoice/deposit
Consulta Crear factura cripto de recarga en la referencia de la API.
Ejemplo de solicitud:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com"
}
La respuesta devuelve los datos de pago que tu aplicación debe mostrar al cliente.
Ejemplo de respuesta:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com",
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"addressOldFormat": null,
"destinationTag": null,
"senderAmount": 100,
"receiverAmount": 100,
"expirationDate": "2026-01-15T10:30:00",
"expirationDateMillis": 1768473000000
}
Los montos de estos ejemplos son ilustrativos. Los valores reales de senderAmount y receiverAmount dependen de las monedas elegidas, el tipo de cambio y las comisiones aplicables.
Campos de la solicitud de factura
| Campo | Obligatorio | Descripción |
|---|---|---|
receiverCurrency | Sí | Moneda que se acredita en tu cuenta de Volet.com cuando se completa el pago. Consulta los valores admitidos en la referencia de la API. |
senderCurrency | Sí | Moneda y red que debe usar el cliente para pagar, por ejemplo USDT_TRC20. |
amount | Sí | Monto del pago. Cómo se interpreta depende de transferAction. |
transferAction | Sí | Define a qué lado se refiere amount. Valores posibles: GIVE, GET. Consulta GIVE y GET. |
note | No | Nota del pago o descripción del pedido. Hasta 255 caracteres. |
sciName | No* | Nombre del Hosted Checkout configurado en tu cuenta de Volet.com. Actualmente es obligatorio si quieres obtener el pedido con GET /api/orders o recibir notificaciones a la Status URL mediante la configuración de Hosted Checkout. |
orderId | No* | ID interno de tu pedido, hasta 64 caracteres. Es obligatorio para obtener el pago más adelante con GET /api/orders. Usa un valor único para cada pago. |
subMerchantURL | No | URL del sitio web del subcomercio, si el pago se procesa en nombre de otro comercio. Consulta Subcomercios. |
* El endpoint de creación de facturas puede aceptar el campo como opcional, pero es obligatorio para los flujos de seguimiento que describe esta guía.
GIVE y GET
transferAction determina en qué moneda se expresa el amount de la solicitud.
| Valor | Qué significa amount |
|---|---|
GIVE | El monto que envía el cliente, expresado en senderCurrency. |
GET | El monto que se acreditará en tu cuenta de Volet.com, expresado en receiverCurrency. |
Los valores finales de senderAmount y receiverAmount que devuelve la API pueden variar por el tipo de cambio y las comisiones aplicables.
Códigos de moneda
Algunos códigos de criptomonedas incluyen la red blockchain después de un guion bajo.
Por ejemplo:
USDT_TRC20: USDT en Tron.USDT_ERC20: USDT en Ethereum.USDC_SOL: USDC en Solana.
Los demás activos usan un único código de moneda, como BTC, ETH o TON.
Consulta los valores admitidos en Monedas y tokens admitidos y en la referencia de la API.
Campos de la respuesta de factura
| Campo | Descripción |
|---|---|
address | Dirección cripto a la que el cliente debe enviar el pago. |
addressOldFormat | Formato alternativo de la dirección, si existe para la red elegida. |
destinationTag | Etiqueta de destino, memo u otro identificador que exigen algunas redes. |
senderAmount | Monto que debe enviar el cliente. |
senderCurrency | Moneda y red que debe usar el cliente. |
receiverAmount | Monto que se espera acreditar en tu cuenta. |
receiverCurrency | Moneda que se espera acreditar en tu cuenta. |
expirationDate | Fecha y hora de vencimiento de la factura. |
expirationDateMillis | Vencimiento de la factura como marca de tiempo Unix en milisegundos. |
Muestra siempre exactamente senderAmount, senderCurrency, address y destinationTag, si se devuelve.
Usa expirationDateMillis para calcular y mostrar el vencimiento de la factura.
Paso 3: mostrar las instrucciones de pago
En el modo solo API, tu aplicación es responsable de mostrar las instrucciones de pago al cliente.
Muestra como mínimo:
- El monto a enviar.
- La moneda y la red blockchain.
- La dirección cripto.
- La etiqueta de destino o el memo, si se requiere.
- El plazo de vencimiento.
- Una advertencia de que los fondos solo deben enviarse por la red seleccionada.
Ejemplo:
Send exactly 100 USDT on Tron (TRC-20) to:
TXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This invoice expires at 2026-01-15 10:30 UTC.
Do not send funds on another network.
En las redes que exigen etiqueta de destino o memo, muéstralo claramente junto a la dirección.
Paso 4: consultar el estado del pago
Después de crear la factura, tu backend puede obtener el pedido de pago mediante la API.
Endpoint:
GET /api/orders
Consulta Obtener pedido de pago en la referencia de la API.
Parámetros de consulta actuales:
| Parámetro | Obligatorio | Descripción |
|---|---|---|
orderId | Sí | Identificador del pedido del comercio, hasta 64 caracteres. |
sciName | Sí* | Nombre del Hosted Checkout asociado a la factura. |
* Actualmente, la implementación de la API exige sciName para obtener un pedido.
Ejemplo de solicitud:
GET /api/orders?orderId=ORDER-1001&sciName=Store
sciNamePor ahora, un pedido creado por API no se puede obtener de forma fiable solo con orderId.
Crea una configuración de Hosted Checkout, usa su nombre como sciName al crear la factura cripto y envía el mismo valor a GET /api/orders.
Puedes usar esta solución sin mostrar la página de Hosted Checkout al cliente.
Ejemplo de respuesta:
{
"orderId": "ORDER-1001",
"sciName": "Store",
"paymentStatus": "PENDING",
"paymentMethod": "CRYPTO_INVOICE",
"paymentCreated": "2026-01-15T10:00:00",
"transaction": {
"id": "11111111-1111-4111-8111-111111111111",
"status": "PENDING",
"senderAmount": 100,
"senderCurrency": "USDT_TRC20",
"receiverAmount": 100,
"receiverCurrency": "USD",
"created": "2026-01-15T10:00:00"
},
"invoice": {
"created": "2026-01-15T10:00:00",
"received": "2026-01-15T10:12:00",
"invoiceStatus": "RECEIVED",
"externalStatus": "PAYMENT_RECEIVED",
"penalties": [],
"cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"initialSenderAmount": 100,
"actualReceivedAmount": 100,
"senderCurrency": "USDT_TRC20",
"cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
}
}
Si no se encuentra ningún pedido coincidente, la API puede devolver 404. Revisa orderId y sciName antes de crear otra factura para el mismo pedido.
Estado del pago
Usa paymentStatus del nivel superior para saber si el pago se completó.
| Estado | Significado | Acción recomendada |
|---|---|---|
PENDING | El pago todavía no llegó a un estado final de completado. | Mantén el pedido pendiente. |
COMPLETED | El pago se completó correctamente. | Marca el pedido como pagado y entrega el producto o servicio. |
CANCELED | El pago se canceló. | No entregues el pedido. |
REFUNDED | El pago se reembolsó. | Actualiza el pedido según tu proceso de reembolsos. |
Considera un pedido como pagado solo cuando paymentStatus sea COMPLETED.
La respuesta también incluye campos propios de la factura, como invoiceStatus, externalStatus y penalties. Pueden aportar información adicional sobre la factura cripto.
No deduzcas el estado final del pedido a partir de valores no documentados de externalStatus o penalties. Úsalos solo si tu integración gestiona de forma explícita los valores que devuelve la API.
cryptoCurrencyTransactionId es el identificador de la transacción cripto que devuelve la API. No supongas que su formato es el de un hash de transacción de la blockchain, salvo que se haya confirmado para el flujo de pago elegido.
Recibir notificaciones a la Status URL
Consultar GET /api/orders no es la única forma de seguir las facturas cripto creadas por API.
Por ahora, la configuración de la API en tu cuenta de Volet.com no tiene campos para URL de webhooks. Sin embargo, puedes usar la Status URL configurada para una pasarela de Hosted Checkout para recibir notificaciones del estado de los pagos de las facturas creadas por API.
En este flujo no necesitas mostrar Hosted Checkout ni redirigir a los clientes allí.
Configurar las notificaciones a la Status URL
- Crea una configuración de Hosted Checkout en tu cuenta de Volet.com.
- Configura su Status URL y elige el método HTTP necesario.
- Usa el nombre del Hosted Checkout como
sciNameal crear facturas cripto mediante la API. - Mantén el flujo de pago para el cliente en tu propia aplicación.
- Cuando cambia el estado del pago, Volet.com envía una notificación a la Status URL configurada para ese Hosted Checkout.
- Verifica la firma de la notificación antes de actualizar el pedido en tu sistema.
- Usa
GET /api/orderscomo verificación de conciliación o respaldo cuando haga falta.
Ejemplo de solicitud de factura:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001"
}
En este ejemplo, Store es el nombre de la configuración de Hosted Checkout que contiene la Status URL.
El cliente sigue viendo tu propia interfaz de pago. La página de pago de Hosted Checkout no se abre.
Así, en una integración solo con API, el mismo sciName cumple dos funciones:
- Permite que la implementación actual de
GET /api/ordersencuentre el pedido. - Vincula la factura creada por API con la configuración de Hosted Checkout usada para las notificaciones a la Status URL.
Para los parámetros de las notificaciones y la verificación de la firma, consulta Integración de Hosted Checkout.
Consulta y notificaciones a la Status URL
Puedes usar:
- La consulta por API.
- Las notificaciones a la Status URL.
- Ambas a la vez.
En las integraciones con notificaciones a la Status URL, la consulta por API sirve para la conciliación si una notificación se retrasa o tu endpoint no está disponible temporalmente.
No crees una factura duplicada solo porque falló una consulta de estado o la entrega de una notificación.
Flujo API + Hosted Checkout
Usa este modelo cuando quieras que el propio Hosted Checkout ofrezca la página de pago para el cliente, mientras tu backend usa la API para el seguimiento y la conciliación.
El flujo de pago:
- Crea un pedido en tu sistema.
- Redirige al cliente a Hosted Checkout con tu integración de Hosted Checkout.
- Envía tu
orderIden la solicitud de pago de Hosted Checkout. - El cliente completa el pago en la página de Hosted Checkout.
- Volet.com envía una notificación de estado del pago a tu Status URL.
- Tu backend verifica la firma de la notificación.
- Tu backend actualiza el estado del pedido.
- Opcionalmente, tu backend consulta el pedido mediante la API para conciliarlo.
En este modelo, Hosted Checkout se encarga de:
- La página de pago.
- La elección del método de pago.
- Las instrucciones de pago.
- Las redirecciones del cliente.
La API se puede seguir usando para obtener el pedido de pago por orderId y sciName y conciliar el estado en tu sistema.
Gestión del estado con Hosted Checkout
Si usas la página de Hosted Checkout, no te bases solo en las redirecciones a Success URL o Failed URL.
Las redirecciones del cliente forman parte del flujo del navegador y no siempre llegan a tu servidor.
Usa la notificación a la Status URL para actualizar el pedido en tu backend y la consulta de pedidos por API para la conciliación cuando haga falta.
Enfoque recomendado:
- Recibe la notificación de Hosted Checkout en la Status URL.
- Verifica la firma de la notificación.
- Actualiza el pedido si la notificación es válida.
- Usa
GET /api/orderscomo respaldo o verificación de conciliación.
Consulta Integración de Hosted Checkout para ver el contenido de la notificación y las reglas de verificación de la firma.
Gestión de errores
Los errores de la Merchant API usan una respuesta estructurada con uno o más errores en data.errors.
Ejemplo de estructura:
{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
Campos del error:
| Campo | Descripción |
|---|---|
errorMessage | Código de error legible por máquina que devuelve la API. |
errorType | Categoría del error. |
errorId | Identificador del error que puedes incluir en registros y solicitudes de soporte. |
errorDescription | Descripción del error legible por personas. |
errorField | Campo de la solicitud relacionado con el error, si está disponible. |
params | Parámetros adicionales asociados al error, si están disponibles. |
requestParams | Parámetros de la solicitud asociados al error, si están disponibles. |
Respuestas HTTP habituales:
| Estado HTTP | Significado |
|---|---|
400 | La solicitud tiene un formato incorrecto o contiene parámetros no válidos. |
401 | Faltan los encabezados de autenticación o no son válidos. |
404 | No se encontró el recurso solicitado. |
500 | Error inesperado del servidor. |
Los valores exactos de errorMessage dependen del endpoint y del error. No deduzcas un código de error de la aplicación solo a partir del estado HTTP.
Cuando se produce un error:
- Registra
errorIdpara soporte y diagnóstico. - Revisa
errorFieldcuando esté disponible. - Usa
errorMessage, noerrorDescription, en la gestión programática de errores. - No crees automáticamente una factura duplicada tras un fallo de solicitud con resultado incierto.
- Reintenta solo cuando sea seguro hacerlo.
Pruebas y sandbox
Por ahora, Volet.com no ofrece un sandbox ni un entorno de staging para probar integraciones.
Si usas Hosted Checkout, puedes ver una vista previa de la página de pago para el cliente en la página de Hosted Checkout para desarrolladores. La vista previa no es un sandbox y no reemplaza las pruebas de integración.
Para revisar la API, Hosted Checkout y el flujo de pago antes de salir a producción, contacta al equipo de ventas de Volet.com.
Lista de verificación de pruebas
Antes de aceptar pagos cripto reales, verifica el flujo completo que usa tu integración.
En las integraciones solo con API:
- La verificación de la factura, si se usa.
- La creación de la factura.
- La visualización correcta de la dirección de pago.
- La visualización de la etiqueta de destino o el memo, cuando se requiera.
- La visualización correcta de la moneda y la red.
- La gestión del vencimiento de la factura.
- El almacenamiento de
orderIdysciName. - La consulta del pedido con
GET /api/orders. - La gestión de los pagos completados.
- La gestión de los pagos cancelados y reembolsados.
- La gestión de
orderIdduplicados. - La gestión de errores de la API.
Si usas notificaciones a la Status URL:
- La configuración de Hosted Checkout tiene la Status URL correcta.
- Se envía el mismo nombre de Hosted Checkout como
sciName. - Las notificaciones llegan a tu backend.
- Se verifican las firmas de las notificaciones.
- Las notificaciones duplicadas se gestionan de forma segura.
- La consulta por API se puede usar para la conciliación.
Si usas la página de pago de Hosted Checkout, verifica también:
- La redirección del cliente a Hosted Checkout.
- La redirección a Success URL.
- La redirección a Failed URL.
- La entrega de notificaciones a la Status URL.
- La validación de la firma de las notificaciones.
- La consulta de pedidos por API para la conciliación.
Notas importantes
- En las integraciones solo con API, los clientes no necesitan visitar Hosted Checkout.
- La consulta actual de pedidos exige
sciName. - Una configuración de Hosted Checkout puede usarse solo para
sciNamey las notificaciones a la Status URL, sin mostrar la página de Hosted Checkout. - Usa siempre un
orderIdúnico para cada pago. - Muestra siempre exactamente la dirección, el monto, la moneda, la red y la etiqueta de destino que devuelve la API.
- No marques un pedido como pagado hasta que
paymentStatusseaCOMPLETED. - Usa
expirationDateMillispara calcular el vencimiento de la factura. - Los pagos cripto dependen de las confirmaciones de la blockchain y de las condiciones de la red.
- Enviar fondos a una dirección o red incorrecta puede provocar la pérdida permanente de los fondos.
- No crees automáticamente otra factura tras un tiempo de espera agotado con resultado incierto o un error temporal de la API.
Relacionado
- Crear una pasarela de pago — crea y configura la API y Hosted Checkout
- Aceptar pagos cripto custodiales — cómo funcionan los pagos cripto custodiales
- Integración de Hosted Checkout — usa la página de pago alojada y las notificaciones a la Status URL
- Monedas y tokens admitidos — monedas y redes admitidas
- Referencia de la API — documentación completa de métodos, parámetros y respuestas