Integración de una API de pagos con criptomonedas: qué debe desarrollar realmente tu equipo

Una guía previa al lanzamiento y una explicación paso a paso en video

Pregunta {{n}} de {{t}}

Todo listo para el lanzamiento

Tu equipo tiene respuestas a las preguntas clave. Falta poco para el lanzamiento: haz pruebas con pagos reales antes de empezar a operar.

Ya casi está

Quedan algunos puntos por resolver. Resuélvelos antes del lanzamiento: cada uno se aborda en una sección de este artículo.

Aún no está todo listo

Aún quedan varias decisiones clave por tomar. Hosted Checkout es la opción que más trabajo le ahorra a tu equipo. Puedes solicitar una demostración en vivo al equipo de ventas de Volet.com para conocer primero el flujo de pago.

Lista de verificación de la API antes del lanzamiento

Nueve preguntas que debes responder antes de empezar a operar. Elige la respuesta que se ajuste a tu equipo: cada respuesta muestra una breve nota e indica la sección de este artículo que la explica.

Pregunta 1 de 9

1. ¿El producto requiere una interfaz de pago personalizada?

Sí, necesitamos nuestra propia interfaz

No, una página alojada nos sirve

Aún no lo hemos decidido

Si es así, necesitas una integración solo con API, y tu equipo debe desarrollar y mantener las pantallas de pago. Si no, Hosted Checkout es la opción que requiere menos trabajo y también acepta pagos con el saldo de cuentas de Volet.com.

→ Consulta más abajo: API o Hosted Checkout: una comparación práctica

2. ¿Debemos controlar cada paso del embudo de pago o es aceptable una redirección?

Debemos controlar cada paso

Una redirección nos sirve

Aún no lo hemos decidido

Al redirigir a Hosted Checkout, Volet.com envía notificaciones de estado a tu URL de estado. Si usas tu propia interfaz de pago con la API, tu backend debe consultar el estado del pago por su cuenta.

→ Consulta más abajo: API o Hosted Checkout: una comparación práctica

3. ¿Tenemos capacidad para desarrollar y mantener la interfaz de pago, gestionar los vencimientos y consultar los estados?

Sí, tenemos capacidad

No, Hosted Checkout nos conviene más

Aún no estamos seguros

Con una integración solo con API, tu equipo se encarga de las pantallas de pago, el vencimiento de las facturas (el tipo de cambio de una factura es válido durante 60 o 15 minutos) y las consultas periódicas de estado.

→ Consulta más abajo: Lo que tu equipo realmente necesita desarrollar

4. ¿Hemos definido cómo se vinculan los pedidos internos con los intentos de pago y cómo evitaremos procesar un pedido dos veces?

Sí, está definido

Aún no

Mantén cada pedido separado de sus intentos de pago, usa un orderId único para cada intento y procesa cada pedido una sola vez.

→ Consulta más abajo: Modelo de pedidos y pagos en el backend

5. ¿Hemos decidido cómo conciliar las transacciones del proveedor, los importes recibidos, las comisiones y la moneda de liquidación?

Sí, tenemos un proceso

Aún no

Guarda el ID de transacción de Volet.com, el importe recibido y la moneda de liquidación junto con cada pedido para vincular cada pago con una factura.

→ Consulta más abajo: Modelo de pedidos y pagos en el backend

6. ¿Hemos previsto presupuesto para gestionar los escenarios de error, realizar pruebas de control de calidad de extremo a extremo y monitorear el sistema en producción?

Sí, está en el plan

Aún no

Estima por separado el flujo sin errores y los flujos con errores: gestionar los tiempos de espera agotados, las facturas vencidas y los intentos repetidos requiere dedicar tiempo de desarrollo.

→ Consulta más abajo: Estimación realista del trabajo

7. ¿Hemos decidido cómo gestionar los pagos insuficientes, en exceso, tardíos y enviados por una red incorrecta?

Sí, nuestras reglas están definidas

Aún no

La configuración de la pasarela determina si se aceptan pagos insuficientes y en exceso. Los pagos enviados por una red incorrecta pueden perderse. Incluye tus reglas y tu política de reembolsos en las condiciones de venta.

→ Consulta más abajo: En qué se diferencian los pagos con criptomonedas de los pagos con tarjeta

8. ¿El equipo de finanzas sabe en qué moneda se liquidan los pagos y cómo se cobra la conversión?

Sí, el equipo de finanzas lo sabe

Aún no

Puedes conservar las criptomonedas que recibes o convertirlas automáticamente. Las conversiones entre USD, USDT y USDC se realizan a un tipo de cambio fijo de 1:1; las demás conversiones tienen un costo adicional.

→ Consulta más abajo: Cuánto cuesta usar Volet.com

9. ¿Hemos planificado cómo hacer pruebas con pagos reales, dado que no hay un entorno de pruebas?

Sí, tenemos un plan de pruebas

Aún no

Volet.com no tiene un entorno de pruebas. Solicita una demostración en vivo, crea la pasarela con anticipación y haz pruebas con pagos reales antes del lanzamiento.

→ Consulta más abajo: Pruebas sin sandbox

Tu resultado

Responde las nueve preguntas para ver tu resultado.

Pendiente:

 

En qué se diferencian los pagos con criptomonedas de los pagos con tarjeta

Si tu equipo ya ha integrado pagos con tarjeta, algunas prácticas no serán aplicables. Con las tarjetas, el comercio cobra al cliente. Con las criptomonedas, el cliente envía fondos desde su propia billetera y tu sistema debe responder en función de lo que realmente recibe. Esto cambia los aspectos que debe cubrir la integración.

El importe puede diferir del de la factura. Un cliente puede enviar un poco menos o más de lo solicitado, por ejemplo, por las comisiones de red o las diferencias en el tipo de cambio. Decide de antemano si aceptarás pagos insuficientes y pagos en exceso.

Por ejemplo, puedes aceptar pequeñas diferencias, contactar al cliente o emitir un reembolso. Decidas lo que decidas, indícalo en tus condiciones de venta, junto con las reglas de reembolso y quién paga la comisión de red al realizarlo.

La red importa. Un mismo token existe en varias blockchains. Los fondos enviados por una red incorrecta o a una dirección equivocada pueden perderse.

La cotización vence. El tipo de cambio de una factura es válido durante 60 minutos si liquidas en la misma moneda y durante 15 minutos si se necesita una conversión. Un cliente que paga tarde puede necesitar una nueva solicitud de pago.

La confirmación lleva tiempo. Los fondos se acreditan solo después de que la blockchain confirme el pago, por lo que tu interfaz y la lógica de los pedidos deben contemplar esa espera.

No hay contracargos ni reversiones automáticas. Una transacción confirmada en la blockchain no se puede cancelar. Un reembolso es un pago independiente sujeto a tu propia política y a las normas de protección al consumidor aplicables.

La liquidación es una decisión de negocio. Los fondos se acreditan en tu cuenta de Volet.com una vez que se completa el pago. Puedes conservar las criptomonedas recibidas o convertirlas automáticamente en stablecoins o dinero fiduciario, para que el equipo de finanzas pueda conciliar en una sola moneda y evitar la volatilidad.


Más información: Comisiones de la cuenta de empresa de Volet.com


De qué se encarga Volet.com

Volet.com gestiona las confirmaciones de red. Volet.com monitorea la blockchain, espera las confirmaciones necesarias y acredita los fondos, por lo que tu backend no tiene que rastrear bloques ni contar confirmaciones.

Un único saldo en stablecoins para distintas redes. Una stablecoin recibida en una red se puede retirar a través de otra red compatible sin recurrir a un servicio de puente entre cadenas independiente.

Sin reserva rotativa. Volet.com no retiene parte de tus pagos completados como reserva rotativa.

Tus reglas para pagos insuficientes y en exceso. En la configuración de la pasarela decides si aceptas pagos por debajo o por encima del importe de la factura. Por ejemplo, si tus clientes recargan su saldo contigo, puedes acreditar exactamente lo recibido y aceptar pagos insuficientes. Si un pago supera el importe del pedido, solo se acredita en tu cuenta el importe del pedido.

Gestión de pagos tardíos. Si un pago llega después de que haya vencido la factura, Volet.com lo devuelve al cliente o, en algunos casos, lo acredita en tu cuenta.

Entradas y salidas de fondos. El mismo saldo de Volet.com puede financiar tus pagos salientes: pagos masivos a contratistas, creadores o socios, o retiros para tus propios usuarios. Por ejemplo, una plataforma de intercambio puede aceptar recargas de saldo en criptomonedas de sus usuarios y procesar sus retiros de criptomonedas desde el mismo saldo de Volet.com a través de la API.

Volet.com te ayuda a crear tus pagos globales
En fiat, cripto y stablecoins. Mediante API, hosted checkout o plugins fáciles de instalar. Acepta, envía y gestiona fondos — todo desde el código.

API o Hosted Checkout: una comparación práctica

La decisión clave es qué parte de la experiencia de pago necesita controlar tu producto y cuánto esfuerzo de desarrollo estás dispuesto a invertir en ello.

Elige la integración solo con API cuando necesites una interfaz de pago propia y control sobre todo el proceso de pago. Tu aplicación se encarga de cada paso de cara al cliente, desde mostrar las instrucciones de pago hasta mantenerlo informado hasta que el pago se confirme o venza el plazo para pagar. Tu equipo desarrolla y mantiene todo este proceso.


Guías de Volet.com: Integración de la API


Elige Hosted Checkout si no necesitas una interfaz de pago personalizada ni controlar cada paso del proceso. Volet.com aloja la página de pago, por lo que esta opción suele ser más sencilla y requerir menos trabajo. También funciona dentro de los bots y las miniaplicaciones de Telegram, donde la página de pago se abre en una ventana del navegador integrado (webview).


Lee más: Pagos con criptomonedas en las miniaplicaciones de Telegram: guía de configuración, reglas de Stars y comisiones reales


También puedes combinar Hosted Checkout con la API para consultar y conciliar pedidos. En cualquier caso, Hosted Checkout requiere trabajo de backend. Tu aplicación mantiene sus propios registros de pedidos y los coteja con el estado del pago en Volet.com. Tu backend también firma las solicitudes que envía a Hosted Checkout, lo que ayuda a protegerte de solicitudes manipuladas que podrían desviar el pago de un cliente fuera de tu tienda.

Factor de decisiónSolo APIHosted Checkout
Interfaz de pago para el clienteTu equipo la desarrolla y mantieneAlojada por Volet.com
Control sobre el embudo de pagoAlto: tu aplicación controla la experienciaMás limitado: el cliente sigue el flujo de la página alojada
Esfuerzo de desarrolloMayor: interfaz, consultas de estado, vencimiento y casos límiteMenor para la interfaz de pago; el backend sigue firmando solicitudes de pago, gestionando notificaciones y actualizando pedidos
Ideal paraProceso de pago personalizado en un sitio web, una aplicación, un bot o una plataformaUn flujo de pago estándar en el que sea aceptable redirigir a una página alojada, incluidos bots y miniaplicaciones de Telegram
Gestión de estadosEl backend consulta el estado del pago a través de la APINotificaciones a la URL de estado y consultas a la API para la conciliación cuando sea necesario
Pago con el saldo de una cuenta de Volet.comNo disponible: la opción de solo API acepta criptomonedas de billeteras externasDisponible: los clientes pueden pagar con el saldo de su cuenta de Volet.com, con una comisión del 0,25 %

Guías de Volet.com: Integración de Hosted Checkout


Volet.com te ayuda a crear tus pagos globales
En fiat, cripto y stablecoins. Mediante API, hosted checkout o plugins fáciles de instalar. Acepta, envía y gestiona fondos — todo desde el código.

Lo que tu equipo realmente necesita desarrollar

Los endpoints de facturación son solo una parte de una implementación que usa únicamente la API. Antes de elegir esta opción, ten en cuenta las responsabilidades de producto y operaciones que se detallan a continuación.

Cómo funciona el flujo usando solo la API:

  1. Crea el pedido en tu propio sistema.
  2. Crea una factura en criptomonedas a través de la API.
  3. Muestra al cliente la dirección, el importe, la moneda, la red y la hora de vencimiento que devuelve la API.
  4. El cliente envía el pago desde su billetera.
  5. Tu backend consulta el estado del pago a través de la API.
  6. Una vez confirmado el pago, marca el pedido como pagado y tramítalo.

Cómo funciona el flujo con Hosted Checkout y la API:

  1. Crea el pedido en tu sistema y redirige al cliente a Hosted Checkout con tu orderId.
  2. El cliente paga en la página de Hosted Checkout.
  3. Volet.com envía una notificación a tu URL de estado, el endpoint de tu servidor que recibe actualizaciones de los pagos.
  4. Tu backend verifica la firma y, si es necesario, confirma el pedido a través de la API.
  5. Marca el pedido como pagado y tramítalo.

Interfaz de pago y ciclo de vida de la factura. Tu aplicación debe mostrar con precisión los datos de pago que devuelve la API: importe que se debe enviar, moneda, red blockchain, dirección, cualquier etiqueta de destino o memo y hora de vencimiento. Debe advertir a los clientes que envíen los fondos únicamente a través de la red indicada. Las instrucciones de pago incorrectas pueden provocar la pérdida de fondos, por lo que este es un requisito funcional, no un detalle visual.

No le indiques al cliente que un pago ha fallado o se ha completado hasta que el estado del pago lo confirme.

Modelo de pedidos y pagos en el backend. Mantén el pedido interno separado del intento de pago o de la factura. Esto facilita la gestión de procesos de pago abandonados, facturas vencidas, clientes que vuelven a intentar pagar y actualizaciones de estado que llegan después de que el usuario haya salido de la página.

Usa un orderId único para cada intento de pago, tal como se describe en la documentación de la API. Define en tu propia base de datos cómo se vincula cada intento con el pedido. Guarda con cada pedido el ID de transacción de Volet.com, el importe recibido y la moneda de liquidación, para que el equipo de finanzas pueda asociar cada pago con una factura sin recurrir a hojas de cálculo manuales. El tratamiento fiscal de los ingresos en criptomonedas depende de tu jurisdicción, así que defínelo con tu contador.

Elige cómo se determina el importe de la factura. Decide si el precio del pedido se fija en la moneda que esperas recibir o si el cliente debe enviar un importe fijo de una criptomoneda específica. Esta elección afecta la visualización de precios, la conciliación y la forma de explicar el importe a pagar. Asegúrate de que sea coherente con tu modelo de precios y contabilidad, y valida los valores calculados antes de crear facturas para pagos reales. La documentación de la API explica cómo configurar cada opción.


Guías de Volet.com: Integración de la API


Supongamos que tu cliente hace un pedido por €120 y paga con criptomonedas. Tu backend debe conservar suficiente información para vincular el pago completado con el pedido original. Para este pago, almacenaría lo siguiente:

  • El ID de tu pedido (ORD-10482) identifica la compra en tu sistema.
  • El ID de la transacción de Volet.com (VLT-839201) vincula el pago con la transacción registrada en Volet.com.
  • El importe recibido (unos 139 USDT) muestra lo que el cliente realmente envió.
  • La moneda de liquidación (EUR) indica la moneda en la que tu equipo de finanzas lleva la contabilidad.
  • El estado del pago (final, confirmado por la API) indica si el pago puede considerarse completado.

Para realizar la conciliación, vincula la transacción de Volet.com con el intento de pago y el pedido; luego compara el ID de la transacción, los importes esperado y recibido, la moneda y el estado final del pago. Si falta un pago, llega tarde o no coincide con el importe esperado, márcalo para revisión en lugar de marcar automáticamente el pedido como pagado.

Un cliente crea un pedido, abre la página de pago y envía las criptomonedas requeridas. Antes de que la blockchain confirme la transacción, cierra la pestaña del navegador y sale de tu sitio web.

Tu backend continúa monitoreando el pago:

  1. El pedido del cliente permanece pendiente en tu sistema.
  2. El intento de pago continúa de forma independiente. En una integración solo con API, tu backend consulta su estado a través de la API. Con Hosted Checkout, Volet.com envía una notificación a tu URL de estado.
  3. Tu backend verifica el estado del pago a través de la API.
  4. Una vez que se confirma que el pago se completó, tu sistema marca el pedido como pagado e inicia su procesamiento.
  5. Si el cliente vuelve a tu sitio web, ve el estado actualizado del pedido.

Lo importante: cerrar la página de pago no cancela el pago ni lo confirma. Tu backend, no la redirección del navegador, determina cuándo se puede procesar el pedido.

Gestión de estados y recuperación. Si usas solo la API, tu equipo debe elegir una estrategia de consulta periódica (con qué frecuencia el backend comprueba el estado), evitar solicitudes innecesarias y gestionar los fallos temporales de consulta sin cambiar incorrectamente el estado del pedido.

Considera cada notificación como una señal, no como un comprobante de pago: verifica su firma y consulta el pedido a través de la API antes de procesarlo. Procesa cada pedido una sola vez, usando tu propio orderId como identificador, para que una notificación repetida o una segunda comprobación del estado no provoquen que se procese dos veces.

Procesa un pedido solo después de que la API confirme que el pago se ha completado, no cuando se cree la factura correctamente ni cuando el navegador redirija al cliente. La documentación de la API describe los valores exactos de los estados y cómo gestionar cada uno.


Guías de Volet.com: Integración de la API


Una solicitud puede agotar el tiempo de espera aunque el sistema remoto ya la haya procesado. No vuelvas a intentar crear la factura a ciegas tras un fallo cuyo resultado no esté claro. Antes de decidir qué hacer, registra el errorId de la API, comprueba el estado actual del pedido y del pago, y sigue las instrucciones de gestión de errores de la documentación. Nunca crees automáticamente un pedido duplicado y reintenta una solicitud solo cuando sea seguro hacerlo.

Seguridad y preparación operativa. Guarda los secretos de la API y las credenciales de autenticación en el servidor. Nunca los expongas en el código del frontend, aplicaciones móviles, bots ni scripts del lado del cliente. Configura solo los permisos que requiera la integración y restringe el acceso a la API a las direcciones IP de tus servidores: no se recomienda permitir todas las IP en producción.

Diseño de un flujo de pago confiable

Un flujo de pago debe contemplar más que el caso en el que todo sale bien.

Decide qué debe hacer el producto cuando:

  • se agote el tiempo de espera al crear una factura y se desconozca el resultado;
  • falle temporalmente una consulta de estado;
  • una factura venza antes de que el cliente pague;
  • el cliente abandone el proceso de pago y regrese más tarde;
  • el cliente inicie otro intento de pago;
  • una notificación de estado se retrase o se reciba más de una vez.

El objetivo es evitar que un pedido se procese dos veces, mantener la coherencia del estado interno del pedido e indicar al cliente con claridad el siguiente paso.


Guías de Volet.com: Guía de la API con las definiciones exactas de los estados y los campos de respuesta


Pruebas sin sandbox

Volet.com no tiene sandbox ni entorno de pruebas. Tenlo en cuenta desde el principio, en lugar de descubrirlo en el lanzamiento:

  • Solicita una demostración en vivo al equipo de ventas de Volet.com para conocer el flujo de pago, la API y Hosted Checkout antes de empezar a desarrollar.
  • Crea la pasarela con anticipación. Toda pasarela con custodia nueva (en la que Volet.com mantiene los fondos recibidos en tu cuenta) pasa por una revisión de cumplimiento normativo que suele tardar unas horas. Mientras tanto, puedes terminar la integración.
  • Haz pruebas con pagos reales en producción: pagos exitosos y fallidos, vencimiento de facturas y pagos insuficientes y en exceso. Cada pago de prueba con criptomonedas es una transacción real en la blockchain y conlleva una comisión de red.
  • En Hosted Checkout, comprueba también la entrega de notificaciones a la URL de estado, la validación de firmas y las redirecciones de éxito y error.
  • Identifica los pedidos de prueba en tu base de datos para que no se mezclen con los ingresos reales durante la conciliación.

Estimación realista del trabajo

El esfuerzo real depende de la arquitectura actual de tu proceso de pago, la experiencia de usuario requerida, la experiencia de tus desarrolladores con las API de pagos y el alcance de las pruebas de control de calidad (QA).

Área de trabajoSolo APIHosted Checkout
Configuración de la cuenta y la pasarelaVerificación de la cuenta, configuración de la API, permisos y aprobaciónVerificación de la cuenta, configuración de Hosted Checkout y cualquier aprobación necesaria
Implementación principalCreación de facturas, interfaz de pago, consultas de estado y actualizaciones de pedidosFlujo de redirección, gestión de la URL de estado y actualizaciones de pedidos en el backend
Casos límiteVencimiento, tiempos de espera agotados con resultado incierto, reintentos, intentos duplicados e instrucciones sobre la redValidación de notificaciones, casos límite en las redirecciones y conciliación
Control de calidadVisualización de los datos de pago, consultas de estado, vencimiento, fallos y recuperaciónRedirecciones, entrega de notificaciones, validación de firmas y conciliación
Responsabilidades continuasMantenimiento de la interfaz de usuario, monitoreo, diagnóstico para soporte y gestión de estadosMonitoreo del backend, conciliación de pedidos y gestión de callbacks

Estima por separado el trabajo necesario para los flujos exitosos y los flujos con fallos, e incluye tiempo para las pruebas de extremo a extremo y el monitoreo en producción.

Cuánto cuesta usar Volet.com

Desde el 0,25 % para pagos con stablecoins y criptomonedas. Las conversiones entre USD, USDT y USDC se realizan a un tipo de cambio fijo de 1:1; las demás conversiones se cobran por separado. El cliente paga la comisión de la red blockchain. Sin comisión de configuración ni cuota mensual. Tú eliges quién paga la comisión de procesamiento. Para volúmenes elevados, el equipo de ventas puede ofrecer tarifas personalizadas.

Acepta USDT, USDC y los principales tokens cripto en todo el mundo
Empieza con la pasarela de pagos cripto — liquidaciones instantáneas y comisiones desde 0,25%

Preguntas frecuentes

No. Volet.com no tiene un entorno de pruebas. Puedes solicitar una demostración en vivo al equipo de ventas. Antes del lanzamiento, prueba en tu sistema los pagos exitosos y fallidos, el vencimiento de facturas y los pagos insuficientes y en exceso.

Las nuevas pasarelas con custodia pasan primero por una revisión de cumplimiento normativo. Suele tardar unas horas. Tu cuenta debe estar verificada antes de crear la pasarela. Aprovecha la espera para terminar la integración.

No. Con una integración solo con API, tu backend consulta el estado del pago por su cuenta. Si necesitas notificaciones, usa Hosted Checkout junto con la API.

La configuración de tu pasarela determina si se aceptan pagos insuficientes y en exceso. Si un pago llega después de que haya vencido la factura, Volet.com lo devuelve al cliente o, en algunos casos, lo acredita en tu cuenta. Si el cliente aún quiere pagar, puede que necesite una nueva solicitud de pago.

Consulta el pedido a través de la API con tu orderId antes de responder.

Una transferencia puede ser visible en la cadena de bloques y aun así no coincidir con la factura: el importe puede ser insuficiente, el pago puede haber llegado fuera de plazo o haberse enviado por otra red.

Dale a tu equipo de soporte acceso a los detalles del pago y acuerda con él de antemano cuándo derivar un caso al soporte de Volet.com.

No. Una transacción confirmada en la cadena de bloques no se puede cancelar y no existen los contracargos de las redes de tarjetas. Un reembolso es un pago independiente, sujeto a tu propia política y a las normas de protección al consumidor aplicables.

No. Volet.com no ofrece adquirencia de tarjetas. Sigue usando tu adquirente de tarjetas para los pagos directos con tarjeta.