Referencia de contratos inteligentes
Esta referencia reúne las direcciones de los contratos, los datos de los tokens y las definiciones de las funciones de los pagos no custodiales de Volet.com en Ethereum, BNB Smart Chain y TRON.
Para instrucciones paso a paso, consulta Integración con Ethereum y BNB Smart Chain o Integración con TRON.
Direcciones de los procesadores de pago
Cada activo compatible usa un contrato inteligente procesador de pagos.
| Red | Activo | Contrato procesador |
|---|---|---|
Ethereum Mainnet (1) | ETH | 0x2fceE245109Cf3c535489a6F52fe11b3BBd644FF |
Ethereum Mainnet (1) | USDT ERC-20 | 0xe4083ED0A1101615b9092E8cD2164e2f42B4571E |
BNB Smart Chain (56) | BNB | 0x2fceE245109Cf3c535489a6F52fe11b3BBd644FF |
BNB Smart Chain (56) | USDT BEP-20 | 0xe4083ED0A1101615b9092E8cD2164e2f42B4571E |
| TRON Mainnet | TRX | TSK9sgBTjvZa6x2yW1bXNWqvQ57WsVUQ3W |
| TRON Mainnet | USDT TRC-20 | TDuE6VueULx5oivQd4MsYr9DEhNMgXNfTm |
Antes de procesar pagos, confirma con Volet.com las direcciones de los contratos desplegados y la ABI. Los contratos de otras redes, activos o flujos de pago personalizados pueden usar direcciones e interfaces distintas.
Direcciones y decimales de los tokens
| Red | Activo | Contrato del token | Decimales |
|---|---|---|---|
| Ethereum | ETH (nativo) | N/A | 18 |
| Ethereum | USDT ERC-20 | 0xdAC17F958D2ee523a2206206994597C13D831ec7 | 6 |
| BNB Smart Chain | BNB (nativo) | N/A | 18 |
| BNB Smart Chain | USDT BEP-20 | 0x55d398326f99059fF775485246999027B3197955 | 18 |
| TRON | TRX (nativo) | N/A | 6 (SUN) |
| TRON | USDT TRC-20 | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
Todos los montos del contrato inteligente deben expresarse en las unidades mínimas del activo.
- ETH y BNB: usa
ethers.parseEther()para convertir los montos a wei. - USDT en EVM: usa
ethers.parseUnits(amount, tokenDecimals)con la precisión del token correspondiente. - TRX: usa SUN, donde 1 TRX = 1.000.000 SUN.
- USDT en TRON: usa unidades base enteras del token, donde 1 USDT = 1.000.000 unidades.
No uses aritmética de punto flotante para calcular los montos de los pagos.
Interfaz del contrato de pago
El procesador de pagos estándar ofrece dos funciones principales: previewPayment() y transfer().
interface IVoletPaymentProcessor {
function previewPayment(
uint256 amount,
bool buyerPaysCommission
) external view returns (
uint256 commission,
uint256 totalPay
);
function transfer(
address seller,
uint256 amount,
bool buyerPaysCommission,
address optionalCommissionWallet
) external payable;
}
Esta interfaz describe las funciones de pago que se usan en las guías de integración. Usa la ABI verificada completa del contrato desplegado para decodificar eventos o manejar errores propios del contrato.
previewPayment()
Calcula la comisión de procesamiento y el monto total que debe pagar el cliente.
Parámetros
| Parámetro | Tipo | Descripción |
|---|---|---|
amount | uint256 | Monto de pago solicitado en las unidades mínimas del activo |
buyerPaysCommission | bool | Determina si la comisión de procesamiento se suma al pago del cliente o se descuenta de los ingresos del comercio |
Valores devueltos
| Parámetro | Tipo | Descripción |
|---|---|---|
commission | uint256 | Comisión de procesamiento en las unidades mínimas del activo |
totalPay | uint256 | Monto total que debe pagar el cliente, en las unidades mínimas del activo |
En los pagos con el activo nativo, pasa totalPay como value de la transacción en EVM o como callValue en TRON.
En los pagos en USDT, el saldo de tokens del cliente y la autorización de gasto (allowance) del procesador deben ser de al menos totalPay.
Usa siempre los valores que devuelve previewPayment(). No calcules la comisión de procesamiento manualmente.
transfer()
Ejecuta el pago y distribuye los fondos según la configuración de comisiones del contrato.
Parámetros
| Parámetro | Tipo | Descripción |
|---|---|---|
seller | address | Billetera receptora del comercio |
amount | uint256 | Monto de pago solicitado en las unidades mínimas del activo |
buyerPaysCommission | bool | Determina quién paga la comisión de procesamiento |
optionalCommissionWallet | address | Billetera de comisión del socio, o la dirección cero de la red si no aplica |
Direcciones cero
| Red | Dirección cero |
|---|---|
| Ethereum / BNB Smart Chain | 0x0000000000000000000000000000000000000000 |
| TRON (Base58) | T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb |
La función transfer() no acepta el parámetro orderId. Tu backend debe asociar el hash de cada transacción de pago (txid) con su pedido.
Consulta Verificación de pagos y seguimiento de pedidos para asociar transacciones y evitar pagos duplicados.
Evento de pago
Los procesadores de pago emiten el evento PaymentProcessed después de distribuir el pago al comercio.
event PaymentProcessed(
address indexed buyer,
address indexed seller,
uint256 commission,
uint256 totalPay
);
| Parámetro | Tipo | Descripción |
|---|---|---|
buyer | address | Billetera que inició el pago |
seller | address | Billetera receptora del comercio |
commission | uint256 | Comisión de procesamiento en las unidades mínimas del activo |
totalPay | uint256 | Monto total pagado por el comprador en las unidades mínimas del activo |
El monto que recibe el comercio es:
receivedAmount = totalPay - commission
Esta fórmula se aplica sea cual sea el valor de buyerPaysCommission.
En los pagos con ETH, BNB y TRX nativos, una transacción exitosa y finalizada con un evento PaymentProcessed auténtico y coincidente confirma el pago al comercio según la implementación documentada del procesador.
En los pagos en USDT, verifica además el evento Transfer del token desde el procesador de pagos hacia el comercio por el monto esperado.
Verifica siempre que la dirección del contrato que emite el evento coincida con la dirección aprobada del procesador.
Consulta Verificación de pagos y seguimiento de pedidos para ver ejemplos de implementación.
Comisiones de procesamiento
El parámetro buyerPaysCommission determina cómo se aplica la comisión de procesamiento.
| Valor | El cliente paga | El comercio recibe |
|---|---|---|
true | Monto solicitado + comisión de procesamiento | Monto solicitado |
false | Monto solicitado | Monto solicitado − comisión de procesamiento |
La comisión de procesamiento real y el monto total del pago los calcula previewPayment() según el contrato desplegado.
Las comisiones de red de la blockchain son independientes de la comisión de procesamiento:
- Ethereum / BNB Smart Chain: comisiones de gas que se pagan en ETH o BNB.
- TRON: costos de Energy y Bandwidth, que pueden pagarse en TRX.
Liquidación
Con los pagos no custodiales, el contrato inteligente transfiere los fondos directamente a la billetera receptora del comercio.
Los fondos no se acreditan en una cuenta de Volet.com, y la conversión automática a fiat no forma parte de este flujo de pago.
Errores del contrato
El procesador de pagos puede devolver los siguientes errores:
| Error | Descripción |
|---|---|
SellerZeroAddress | La dirección receptora del comercio es cero |
SellerIsBuyer | Las direcciones de la billetera del comprador y del comercio son iguales |
AmountIsZero | El monto del pago es cero |
InvalidTotalAmountValidation | El value o callValue del activo nativo no coincide con el total esperado |
CommissionExceedsAmount | La comisión de procesamiento supera el monto disponible para descontarla |
SellerNotWhitelisted | Es posible que el contrato desplegado no autorice la billetera del comercio |
EnforcedPause | El procesamiento de pagos está en pausa |
Los errores disponibles y su comportamiento exacto dependen del contrato desplegado. Usa su ABI verificada para decodificar los errores personalizados.
Para ver las causas y las acciones recomendadas, consulta Solución de problemas de pagos con contratos inteligentes.
Guías relacionadas
- Integración con contratos inteligentes: descripción general de la integración de 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.
- Verificación de pagos y seguimiento de pedidos: verifica las transacciones y asocia los pagos con los pedidos.
- Solución de problemas: resuelve errores frecuentes de billeteras y pagos.