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.

Puedes usar la API de dos formas:

Solo API: tu aplicación crea toda la experiencia de pago y muestra al cliente la dirección cripto, el monto, la red y el plazo de vencimiento.
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 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	Creada por tu aplicación	Crear la factura, mostrar los datos de pago, seguir el estado	Consultar periódicamente el estado del pago mediante la API
API + Hosted Checkout	Alojada por Volet.com	Crear o seguir pedidos, conciliar el estado del pago	Usar la Status URL de Hosted Checkout y la consulta de pedidos por API

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.
Permisos de API para aceptar pagos cripto.
Una configuración de Hosted Checkout si usas la API junto con Hosted Checkout.

Consulta Crear una pasarela de pago para crear y configurar tu API.

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 de autenticación de la solicitud, generado con el secreto de tu API.

Mantén en privado el secreto 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.

Flujo solo con API

Usa este flujo cuando tu aplicación gestiona toda la experiencia de pago cripto.

El flujo de pago:

Crea un pedido en tu sistema.
Opcionalmente, verifica los datos de la factura antes de crearla.
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.
Tu backend consulta el estado del pago mediante la API.
Cuando el pago se completa, actualiza el estado del pedido en tu sistema.

Paso 1: 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

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

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
}

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.
`senderCurrency`	Sí	Moneda y red que debe usar el cliente para pagar.
`amount`	Sí	Monto del pago. Cómo se interpreta depende de `transferAction`.
`transferAction`	Sí	Define si el monto es el monto a enviar o el monto a recibir. Valores posibles: `GIVE`, `GET`.
`note`	No	Nota del pago o descripción del pedido.
`sciName`	No	Nombre del Hosted Checkout o de la tienda asociado al flujo de pago.
`orderId`	No	ID interno de tu pedido. 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.

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 acredita en tu cuenta.
`expirationDate`	Fecha y hora de vencimiento de la factura.
`expirationDateMillis`	Marca de tiempo de vencimiento de la factura en milisegundos.

Muestra siempre exactamente senderAmount, senderCurrency, address y destinationTag, si se devuelve.

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 de instrucción:

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 debe consultar el estado del pago.

Endpoint:

GET /api/orders

Parámetro de consulta obligatorio:

Parámetro	Descripción
`orderId`	Identificador del pedido del comercio.

Parámetro de consulta opcional:

Parámetro	Descripción
`sciName`	Nombre del Hosted Checkout o de la tienda asociado al pedido.

Ejemplo de solicitud:

GET /api/orders?orderId=ORDER-1001&sciName=Store

Ejemplo de respuesta:

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PROCESSING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:30:00",
  "transaction": {
    "status": "PROCESSING"
  },
  "invoice": {
    "invoiceStatus": "PROCESSING",
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Estados del pago

Usa paymentStatus para decidir cómo actualizar el pedido en tu sistema.

Estado	Significado	Acción recomendada
`CREATED`	La factura se creó y está a la espera del pago.	Mantén el pedido pendiente.
`PROCESSING`	El pago se detectó o se está procesando.	Mantén el pedido pendiente y sigue consultando.
`COMPLETED`	El pago se completó correctamente.	Marca el pedido como pagado y entrega el producto o servicio.
`FAILED`	El pago falló, venció o no pudo completarse.	No entregues el pedido. Pide al cliente que inicie un nuevo pago.

Considera el pedido como pagado solo cuando el estado pase a COMPLETED.

Flujo API + Hosted Checkout

Usa este modelo cuando quieras que Hosted Checkout gestione la página de pago para el cliente y tu backend mantenga el control por API del seguimiento y la conciliación de pedidos.

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 orderId en 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 también 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 y las redirecciones del cliente.

La API se puede seguir usando para obtener la orden de pago por orderId y conciliar el estado final en tu sistema.

Gestión del estado con Hosted Checkout

Con 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 y la consulta de pedidos por API para actualizar el estado del pedido de forma fiable.

Enfoque recomendado:

Recibe la notificación de Hosted Checkout en la Status URL.
Verifica la firma de la notificación.
Actualiza el estado del pedido si la notificación es válida.
Usa la consulta de pedidos por API como respaldo o verificación de conciliación.

Gestión de errores

Los errores de la Merchant API devuelven una respuesta de error estructurada.

Casos de error 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.
`403`	La API no tiene permiso para usar la operación solicitada.
`404`	No se encontró el recurso solicitado.
`500`	Error inesperado del servidor.

Cuando se produce un error:

Registra errorId para soporte y diagnóstico.
Revisa errorField para identificar el campo de la solicitud relacionado con el error.
No crees automáticamente un pedido duplicado.
Reintenta solo cuando sea seguro hacerlo.

Lista de verificación de pruebas

Antes de aceptar pagos cripto reales, prueba el flujo completo.

En las integraciones solo con API, verifica:

La verificación de la factura.
La creación de la factura.
La visualización de la dirección de pago.
La visualización de la etiqueta de destino o el memo, cuando se requiera.
La gestión del vencimiento de la factura.
La consulta periódica del estado del pedido.
La gestión de los pagos completados.
La gestión de los pagos fallidos o vencidos.
La gestión de orderId duplicados.

En las integraciones API + Hosted Checkout, verifica también:

La redirección del cliente a Hosted Checkout.
La entrega de notificaciones a la Status URL.
La validación de la firma de las notificaciones.
Las redirecciones a Success URL y Failed URL.
La consulta de pedidos por API para la conciliación.

Notas importantes

Las integraciones solo con API no usan los callbacks de Hosted Checkout.
Tu backend debe consultar el estado del pago mediante la API.
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 el estado del pago sea COMPLETED.
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.

Crear una pasarela de pago — crea y configura tu API
Aceptar pagos cripto custodiales — cómo funcionan los pagos cripto custodiales
Integración de Hosted Checkout — usa la página de pago alojada
Referencia de la API — documentación completa de métodos, parámetros y respuestas

Cuándo usar la integración por API​

Modelos de integración​

Antes de empezar​

Autenticación​

Flujo solo con API​

Paso 1: verificar los datos de la factura​

Paso 2: crear una factura cripto​

Campos de la solicitud de factura​

Campos de la respuesta de factura​

Paso 3: mostrar las instrucciones de pago​

Paso 4: consultar el estado del pago​

Estados del pago​

Flujo API + Hosted Checkout​

Gestión del estado con Hosted Checkout​

Gestión de errores​

Lista de verificación de pruebas​

Notas importantes​

Relacionado​

Cuándo usar la integración por API

Modelos de integración

Antes de empezar

Autenticación

Flujo solo con API

Paso 1: verificar los datos de la factura

Paso 2: crear una factura cripto

Campos de la solicitud de factura

Campos de la respuesta de factura

Paso 3: mostrar las instrucciones de pago

Paso 4: consultar el estado del pago

Estados del pago

Flujo API + Hosted Checkout

Gestión del estado con Hosted Checkout

Gestión de errores

Lista de verificación de pruebas

Notas importantes

Relacionado