Solución de problemas de pagos con contratos inteligentes
Usa esta guía para resolver problemas frecuentes al aceptar pagos no custodiales con contratos inteligentes de Volet.com en Ethereum, BNB Smart Chain y TRON.
Busca el problema a continuación y sigue los pasos recomendados. Las direcciones de los contratos, los parámetros y las definiciones de errores están en la Referencia de contratos inteligentes.
Problemas de billetera y red
| Problema | Causa posible | Cómo resolverlo |
|---|---|---|
| Conexión de billetera rechazada | El cliente rechazó la solicitud o la billetera está bloqueada | Pide al cliente que desbloquee la billetera y vuelva a conectarse |
| MetaMask no detectado | No hay una billetera de navegador compatible instalada o disponible | Instala MetaMask o conéctate con una billetera compatible con WalletConnect |
| Red EVM incorrecta | La billetera está conectada a una red distinta de la elegida en el pago | Solicita el cambio de red y verifica el chain ID |
| Falla la conexión con WalletConnect | Project ID no válido, configuración incorrecta o billetera o red no compatible | Revisa la configuración del proyecto de Reown y las redes compatibles |
| TronLink no detectado | La extensión no está instalada, activada o desbloqueada | Instala o desbloquea TronLink y recarga la página |
| Red TRON incorrecta | La billetera está conectada a una red de prueba o a una red inesperada | Cambia a TRON Mainnet y verifica la red activa |
Verifica siempre de nuevo la dirección de la billetera y la red elegida antes de iniciar un pago, sobre todo después de conectar la billetera o cambiar de red.
Problemas con la aprobación de USDT
Los pagos en USDT pueden requerir una transacción de aprobación antes de que el contrato procesador pueda transferir los tokens.
| Problema | Causa posible | Cómo resolverlo |
|---|---|---|
| Transacción de aprobación rechazada | El cliente rechazó la solicitud en su billetera | Permite que el cliente vuelva a intentar la aprobación |
| Autorización de gasto (allowance) insuficiente | El procesador no está autorizado a gastar el monto necesario | Revisa allowance() y solicita la aprobación del monto necesario |
| Falla la aprobación de USDT en Ethereum | Una autorización distinta de cero no puede cambiarse directamente a otro monto distinto de cero | Aprueba 0, espera la confirmación y luego aprueba el monto necesario |
| Saldo de USDT insuficiente | El cliente no tiene suficientes tokens para el total del pago | Compara balanceOf() con previewPayment().totalPay |
| La aprobación se completó, pero el pago está pendiente | La aprobación se completó, pero la transacción de pago no se envió o no se verificó | Revisa la autorización actual y luego inicia o verifica la transacción de pago aparte |
Importante: una transacción approve() exitosa no es un pago completado. Solo la transacción transfer() del contrato procesador sirve para verificar el pago del pedido.
Errores de transacciones y contratos
| Error o problema | Causa posible | Cómo resolverlo |
|---|---|---|
InvalidTotalAmountValidation | El value o callValue nativo no coincide con el total esperado del pago | Vuelve a llamar a previewPayment() y envía el totalPay que devuelve |
SellerIsBuyer | Las direcciones de la billetera del comprador y del comercio son iguales | Comprueba que la billetera receptora del comercio sea distinta de la billetera conectada del comprador |
SellerZeroAddress | La dirección receptora del comercio es la dirección cero | Configura una billetera válida del comercio |
AmountIsZero | El monto del pago es cero | Valida el monto del pedido antes de enviar la transacción |
CommissionExceedsAmount | La comisión de procesamiento no puede descontarse del monto solicitado | Revisa el monto del pedido y la configuración de la comisión |
SellerNotWhitelisted | El procesador no autoriza la billetera receptora del comercio | Contacta a Volet.com para revisar la autorización de la billetera |
EnforcedPause | El procesamiento de pagos está en pausa en el contrato | Deja de enviar pagos a través de ese procesador y contacta a Volet.com |
| Falla la transferencia del token | Saldo de tokens o autorización insuficientes, o restricciones propias del token | Verifica el contrato del token, el saldo, la autorización y la red elegida |
| Gas insuficiente | El cliente no tiene suficiente ETH o BNB para la comisión de red | Pide al cliente que mantenga saldo suficiente de la moneda nativa |
| Recursos de TRON insuficientes | El cliente no tiene suficiente Energy, Bandwidth o TRX disponible | Revisa los recursos necesarios y el TRX disponible |
TRON OUT_OF_ENERGY | La ejecución del contrato agotó la Energy disponible o el límite de comisión configurado | Estima el consumo de recursos y revisa el feeLimit de la transacción |
TronGrid HTTP 429 | Se superó el límite de solicitudes de la API | Usa una clave de API en el servidor y reintenta las solicitudes con espera progresiva |
Los errores del contrato dependen del procesador desplegado. Consulta la Referencia de contratos inteligentes para ver las definiciones de los errores.
El pago sigue pendiente
Un pedido puede seguir pendiente aunque el cliente ya haya enviado una transacción.
| Situación | Qué revisar | Acción recomendada |
|---|---|---|
| Se recibió el hash de la transacción, pero no hay recibo | Es posible que la transacción aún no esté incluida en un bloque | Sigue revisando el mismo txid |
| La transacción se ejecutó, pero no está finalizada | Aún no se alcanzó la finalidad de red requerida | Espera la finalidad antes de completar el pedido |
| La aprobación de USDT se confirmó, pero no hay pago | Solo se envió la transacción de aprobación | Comprueba si existe una transacción de pago aparte |
| La transacción fue exitosa, pero el pedido sigue pendiente | Los datos del pago pueden no coincidir con el pedido o la verificación en el backend puede estar incompleta | Compara con el pedido el procesador, el activo, el destinatario, el monto y la llamada al contrato |
| La transacción de TRON es visible, pero no está solidificada | La transacción aún no aparece en los datos del SolidityNode | Sigue revisando el recibo solidificado de la transacción |
| La solicitud RPC falla o agota el tiempo de espera | El proveedor no está disponible temporalmente | Reintenta la verificación sin marcar la transacción como fallida |
| El cliente cerró o recargó la página de pago | La sesión del navegador terminó antes de confirmarse el pago | Continúa la verificación con el proceso de conciliación del backend |
| El pago venció antes de confirmarse | La transacción puede confirmarse después de cerrarse la ventana de pago | Sigue rastreando los intentos de pago enviados y concilia los pagos tardíos |
La transacción fue exitosa, pero el pedido no está marcado como pagado
Que una transacción en la blockchain sea exitosa no significa necesariamente que se haya pagado el pedido correcto.
Tu backend debe confirmar que:
- La transacción usó el contrato procesador esperado.
- El activo y la billetera receptora del comercio coinciden con el pedido.
- El monto del pago y la configuración de la comisión son correctos.
- El comercio recibió los fondos esperados.
- La transacción alcanzó la finalidad requerida en la blockchain.
- El hash de la transacción no se usó ya para otro pedido.
Si algún dato obligatorio no coincide, no marques el pedido como pagado automáticamente. Deja el pago en revisión para investigarlo.
El proceso completo de verificación se describe en Verificación de pagos y seguimiento de pedidos.
Contactar al soporte
Si el problema persiste, contacta a Volet.com e indica:
- La red blockchain y el activo.
- El hash de la transacción de pago (
txid), si lo tienes. - La fecha y hora aproximadas de la transacción.
- El ID del pedido del comercio.
- La dirección del contrato procesador.
- El mensaje de error o una descripción del problema.
Puedes comunicarte con nuestro equipo a través del soporte de Volet.com.
Seguridad: nunca compartas frases semilla de billeteras, claves privadas ni credenciales secretas de API.
Relacionado
- Integración con contratos inteligentes: descripción general de los pagos no custodiales.
- Integración con Ethereum y BNB Smart Chain: acepta ETH, BNB y USDT.
- Integración con TRON: acepta TRX y USDT TRC-20.
- Referencia de contratos inteligentes: direcciones de los contratos, parámetros y errores.
- Verificación de pagos y seguimiento de pedidos: verifica las transacciones y concilia los pedidos.