Integra pagos en USDT BEP-20 en BNB Smart Chain
Agrega a tu sitio un formulario de pagos masivos: el remitente conecta su propia billetera, ingresa los destinatarios y los montos en USDT, revisa la comisión y firma el lote. El contrato de pagos de Volet.com envía USDT BEP-20 desde la billetera del remitente directamente a las billeteras de los destinatarios, así que los fondos nunca pasan por una cuenta de Volet.com.
Esta guía cubre BNB Smart Chain Mainnet. Para otras redes, consulta TRON y Ethereum.
Antes de empezar
- Billetera del remitente — MetaMask u otra billetera de navegador compatible con EIP-1193. Los ejemplos usan MetaMask en Google Chrome.
- Fondos en la billetera del remitente — USDT BEP-20 para los pagos y la comisión de procesamiento, más BNB para las comisiones de red. No necesitas fondear ninguna billetera para crear el formulario: paga el remitente cuando envía un lote.
- Biblioteca — ethers.js v6. No se necesita ningún SDK de Volet.com.
- Sitio web — servido por HTTPS, o desde
localhostdurante el desarrollo. - Backend y base de datos — para guardar cada lote y verificar los pagos.
- Proveedor RPC — un nodo de BNB Smart Chain o un servicio alojado para la verificación en el backend.
Cómo funciona
- El remitente completa el formulario de pagos en tu sitio: direcciones de los destinatarios, montos en USDT y, de forma opcional, la dirección de un socio.
- El remitente conecta su billetera. Tu sitio nunca necesita su clave privada.
- Tu frontend valida el lote y obtiene la comisión de procesamiento del contrato con
previewCommission(). - Tu sitio muestra el total de los pagos, la comisión de procesamiento, el total de USDT necesario y una estimación de la comisión de red.
- Cuando el remitente confirma, tu frontend revisa el saldo de USDT y la autorización de gasto (allowance). Si la autorización no alcanza, la billetera pide al remitente que firme primero una transacción
approve(). - Tu frontend vuelve a revisar la comisión, la billetera, la red y los destinatarios, y luego la billetera pide al remitente que firme
batchPayout(). - Tu backend guarda el hash de transacción (
txid) y verifica la transferencia de USDT a cada destinatario antes de marcar ese pago como completado.
Si falla el pago a un destinatario, los demás no necesariamente se cancelan, así que una transacción exitosa no prueba que todos hayan cobrado. Consulta Paso 7: Verifica cada pago.
Contrato de pagos
| Valor | |
|---|---|
| Red | BNB Smart Chain Mainnet, chain ID 56 (0x38) |
| Contrato de pagos | 0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7 (BscScan) |
| Contrato de USDT | 0x55d398326f99059fF775485246999027B3197955 (Binance-Peg USDT, aparece como BSC-USD) |
| Decimales de USDT | 18 (1 USDT = 10^18 unidades base) |
| Comisión de red pagada en | BNB |
| Dirección cero (sin socio) | 0x0000000000000000000000000000000000000000 |
La misma dirección del contrato de pagos también existe en Ethereum. Son dos despliegues distintos y no son intercambiables: antes de pedir una firma, revisa siempre el chain ID de la billetera y el resultado de usdt() del contrato.
El contrato ofrece estas funciones:
function usdt() external view returns (address);
function MAX_BATCH_SIZE() external view returns (uint256);
function paused() external view returns (bool);
function previewCommission(uint256 total, uint256 count)
external view returns (uint256 commission);
function previewCommissionSplit(uint256 total, uint256 count, address whiteLabel)
external view returns (uint256 platformCommission, uint256 partnerShare);
function getPartner(address partner)
external view returns (bool active, uint16 shareBps);
function batchPayout(
address[] calldata recipients,
uint256[] calldata amounts,
address whiteLabel
) external;
Emite los eventos BatchPayout, PayoutFailed, RefundSent, PartnerNotFound y CommissionTransferFailed. PayoutFailed enumera los destinatarios y los montos que no se pagaron.
Los ejemplos de esta página incluyen solo las funciones y los eventos que usan. Antes de integrar, abre el contrato de pagos en BscScan, toma su ABI completo de la pestaña Contract y compara con él las firmas de las funciones, los tipos de parámetros y los eventos de tu código. Antes de enviar fondos reales, compara también con esta página la dirección del token que devuelve usdt(), los decimales del token, los resultados de previewCommission() y los eventos del contrato.
Comisiones
La comisión de procesamiento es de 0.1 USDT por destinatario del lote, además de los montos de los pagos. Por ejemplo, un lote que paga 10, 20 y 30 USDT a 3 destinatarios necesita 60 USDT para los pagos y 0.3 USDT para la comisión: 60.3 USDT en total.
Muestra siempre al remitente el valor actual de previewCommission(), no una comisión calculada en tu código.
El remitente también paga la comisión de red de BNB Smart Chain en BNB por cada transacción: el pago y, cuando hace falta, la aprobación.
Dirección del socio
batchPayout() recibe el argumento whiteLabel para la billetera opcional de un socio que comparte la comisión de procesamiento. Un lote funciona sin socio: pasa la dirección cero.
Si hay un socio, pasa la dirección de su billetera. getPartner() indica si la dirección es un socio activo y su participación en puntos básicos, y previewCommissionSplit() muestra cómo se reparte la comisión entre Volet.com y el socio. La comisión que paga el remitente no cambia: previewCommission() no depende del socio.
Para registrar la billetera de un socio, escribe a [email protected] con la dirección de la billetera y la red.
Paso 1: Agrega el formulario de pagos
Instala ethers.js:
npm install ethers@^6
Agrega los controles del formulario a tu página. Cada bloque data-payout-row es un destinatario; agrega o quita bloques para cambiar la cantidad de destinatarios.
<input id="partner-wallet" type="text" placeholder="Partner wallet (optional)">
<div data-payout-row>
<input name="address" type="text" placeholder="Recipient address">
<input name="amount" type="text" placeholder="USDT amount">
</div>
<button id="connect" type="button">Connect wallet</button>
<button id="preview" type="button">Preview payouts</button>
<button id="send" type="button">Send payouts</button>
<pre id="summary"></pre>
Antes de llevar el formulario a producción, agrega tus propios estilos, la gestión de filas, los indicadores de progreso y el estado deshabilitado de los botones.
Paso 2: Conecta la billetera del remitente
Crea bnb-payouts.js, un módulo del navegador, y empiézalo con la configuración del contrato y la función de conexión. Los pasos 3 y 4 agregan código al mismo archivo.
import { ethers } from 'ethers';
const CHAIN_ID = 56n;
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0x55d398326f99059fF775485246999027B3197955';
export const USDT_DECIMALS = 18;
const EXPLORER_TX = 'https://bscscan.com/tx/';
export const PAYOUT_ABI = [
'function usdt() view returns (address)',
'function MAX_BATCH_SIZE() view returns (uint256)',
'function paused() view returns (bool)',
'function previewCommission(uint256 total, uint256 count) view returns (uint256)',
'function previewCommissionSplit(uint256 total, uint256 count, address whiteLabel) view returns (uint256 platformCommission, uint256 partnerShare)',
'function getPartner(address partner) view returns (bool active, uint16 shareBps)',
'function batchPayout(address[] recipients, uint256[] amounts, address whiteLabel)',
'event BatchPayout(address indexed sender, uint256 total, uint256 commission, uint256 partnerShare, uint256 count, address indexed whiteLabel)',
'event PayoutFailed(address[] recipients, uint256[] amounts)',
'event RefundSent(address indexed sender, uint256 amount)',
'event PartnerNotFound(address indexed whiteLabel)',
'event CommissionTransferFailed(address indexed wallet, uint256 amount)'
];
const TOKEN_ABI = [
'function decimals() view returns (uint8)',
'function balanceOf(address owner) view returns (uint256)',
'function allowance(address owner, address spender) view returns (uint256)',
'function approve(address spender, uint256 amount) returns (bool)'
];
export async function connect() {
if (!window.ethereum) throw new Error('Install and unlock MetaMask.');
await window.ethereum.request({ method: 'eth_requestAccounts' });
const provider = new ethers.BrowserProvider(window.ethereum);
if ((await provider.getNetwork()).chainId !== CHAIN_ID) {
throw new Error('Select BNB Smart Chain in your wallet, then connect again.');
}
const signer = await provider.getSigner();
const sender = await signer.getAddress();
const payout = new ethers.Contract(PAYOUT_ADDRESS, PAYOUT_ABI, signer);
// Make sure this deployment pays out the expected token.
const tokenAddress = await payout.usdt();
if (tokenAddress.toLowerCase() !== USDT_ADDRESS.toLowerCase()) {
throw new Error('Unexpected USDT token in the payout contract.');
}
const token = new ethers.Contract(tokenAddress, TOKEN_ABI, signer);
if (Number(await token.decimals()) !== USDT_DECIMALS) {
throw new Error('Unexpected token decimals.');
}
return { sender, payout, token };
}
// Signatures go only to the wallet and network the batch was reviewed with.
async function assertWalletUnchanged(session) {
const [chainId, accounts] = await Promise.all([
window.ethereum.request({ method: 'eth_chainId' }),
window.ethereum.request({ method: 'eth_accounts' })
]);
if (BigInt(chainId) !== CHAIN_ID ||
accounts[0]?.toLowerCase() !== session.sender.toLowerCase()) {
throw new Error('Wallet or network changed. Connect again and review the batch.');
}
}
Llama a connect() solo cuando el remitente selecciona Connect wallet, nunca al cargar la página. Si la billetera está en otra red, pide al remitente que cambie a BNB Smart Chain.
Paso 3: Muestra el lote y la comisión
Agrega las funciones de validación y vista previa a bnb-payouts.js. quote() convierte las filas del formulario en argumentos del contrato en unidades base de USDT y obtiene la comisión, el saldo y la autorización de gasto.
function parseRows(rows) {
if (!Array.isArray(rows) || rows.length === 0) {
throw new Error('Add at least one recipient.');
}
const recipients = rows.map((row) => {
if (!ethers.isAddress(row.address)) throw new Error(`Invalid recipient address: ${row.address}`);
const address = ethers.getAddress(row.address);
if (address === ethers.ZeroAddress) throw new Error('The zero address cannot receive a payout.');
return address;
});
const amounts = rows.map((row) => {
if (typeof row.amount !== 'string' || !/^\d+(\.\d{1,18})?$/.test(row.amount)) {
throw new Error(`Invalid USDT amount: ${row.amount}`);
}
const amount = ethers.parseUnits(row.amount, USDT_DECIMALS);
if (amount <= 0n) throw new Error('Each amount must be positive.');
return amount;
});
return { recipients, amounts };
}
export async function quote(session, rows, partnerWallet = null) {
const { payout, token, sender } = session;
const { recipients, amounts } = parseRows(rows);
if (await payout.paused()) throw new Error('The payout contract is paused.');
if (BigInt(recipients.length) > await payout.MAX_BATCH_SIZE()) {
throw new Error('The batch has more recipients than the contract allows.');
}
if (partnerWallet && !ethers.isAddress(partnerWallet)) {
throw new Error('Invalid partner address.');
}
const whiteLabel = partnerWallet ? ethers.getAddress(partnerWallet) : ethers.ZeroAddress;
const total = amounts.reduce((sum, amount) => sum + amount, 0n);
const commission = await payout.previewCommission(total, recipients.length);
const [platformCommission, partnerShare] = await payout.previewCommissionSplit(
total, recipients.length, whiteLabel
);
return {
recipients, amounts, whiteLabel, total, commission,
platformCommission, partnerShare,
required: total + commission,
balance: await token.balanceOf(sender),
allowance: await token.allowance(sender, PAYOUT_ADDRESS)
};
}
Muestra al remitente total, commission y required, con el formato de ethers.formatUnits(value, USDT_DECIMALS), junto con una estimación de la comisión de red en BNB. No conviertas montos con aritmética de punto flotante: parseUnits() los mantiene exactos.
Un pago enviado a una dirección equivocada no se puede cancelar ni devolver. Muestra al remitente cada dirección y cada monto antes de que firme, y acepta solo direcciones de BNB Smart Chain que puedan recibir USDT BEP-20.
Paso 4: Aprueba USDT y envía el lote
Agrega la función de envío a bnb-payouts.js. Comprueba que nada cambió desde que el remitente revisó el lote, pide una aprobación si la autorización de gasto no alcanza y luego envía batchPayout().
function sameBatch(a, b) {
return a.required === b.required &&
a.whiteLabel === b.whiteLabel &&
a.recipients.length === b.recipients.length &&
a.recipients.every((address, i) => address === b.recipients[i] && a.amounts[i] === b.amounts[i]);
}
async function confirmed(tx, message) {
const receipt = await tx.wait();
if (!receipt || receipt.status !== 1) throw new Error(message);
}
export async function send(session, rows, reviewed, partnerWallet = null) {
const { payout, token } = session;
await assertWalletUnchanged(session);
const current = await quote(session, rows, partnerWallet);
if (!sameBatch(current, reviewed)) {
throw new Error('The batch or the fee changed. Review the updated quote.');
}
if (current.balance < current.required) throw new Error('Not enough USDT in the sender wallet.');
if (current.allowance < current.required) {
await confirmed(await token.approve(PAYOUT_ADDRESS, current.required), 'USDT approval failed.');
}
// The fee can change while the approval confirms. Check again before the payout signature.
await assertWalletUnchanged(session);
const fresh = await quote(session, rows, partnerWallet);
if (!sameBatch(fresh, reviewed) ||
fresh.balance < fresh.required ||
fresh.allowance < fresh.required) {
throw new Error('The fee, balance or allowance changed. Review the batch before retrying.');
}
const tx = await payout.batchPayout(fresh.recipients, fresh.amounts, fresh.whiteLabel);
return { txid: tx.hash, explorerUrl: EXPLORER_TX + tx.hash };
}
Según la autorización de gasto existente, el remitente firma una o dos transacciones:
| Autorización existente | Transacciones a firmar |
|---|---|
| Suficiente para el lote | Pago |
| Insuficiente | Aprobación, pago |
La aprobación cubre exactamente el monto de este lote, nunca un monto ilimitado. Debe confirmarse antes de la transacción de pago; una transacción approve() no mueve fondos.
Paso 5: Conecta los botones
Conecta el módulo con el formulario. Las solicitudes a la billetera parten solo de los clics del remitente, y los destinatarios y los montos siempre salen del formulario.
import { ethers } from 'ethers';
import { USDT_DECIMALS, connect, quote, send } from './bnb-payouts.js';
const $ = (selector) => document.querySelector(selector);
let session = null;
let reviewed = null;
function readRows() {
return [...document.querySelectorAll('[data-payout-row]')].map((row) => ({
address: row.querySelector('[name="address"]').value.trim(),
amount: row.querySelector('[name="amount"]').value.trim()
}));
}
function readPartner() {
return $('#partner-wallet').value.trim() || null;
}
function usdt(units) {
return `${ethers.formatUnits(units, USDT_DECIMALS)} USDT`;
}
function show(text) {
$('#summary').textContent = text;
}
// A quote is valid only for the wallet and network it was made with.
function resetSession() {
session = null;
reviewed = null;
show('Wallet or network changed. Connect again.');
}
window.ethereum?.on?.('accountsChanged', resetSession);
window.ethereum?.on?.('chainChanged', resetSession);
async function onConnect() {
session = await connect();
reviewed = null;
show(`Connected: ${session.sender}`);
}
async function onPreview() {
if (!session) throw new Error('Connect a wallet first.');
reviewed = await quote(session, readRows(), readPartner());
show([
`Payouts: ${usdt(reviewed.total)}`,
`Processing fee: ${usdt(reviewed.commission)}`,
`Total required: ${usdt(reviewed.required)}`
].join(' | '));
}
async function onSend() {
if (!session || !reviewed) throw new Error('Connect a wallet and preview the batch first.');
if (!window.confirm('Send this batch? Your wallet will ask you to sign each transaction.')) return;
const result = await send(session, readRows(), reviewed, readPartner());
reviewed = null;
show(`Submitted: ${result.explorerUrl}`);
// Send result.txid to your backend together with the batch, then verify it (Step 7).
}
for (const [id, handler] of [['#connect', onConnect], ['#preview', onPreview], ['#send', onSend]]) {
$(id).addEventListener('click', () => {
handler().catch((error) => show(error.shortMessage ?? error.message ?? String(error)));
});
}
Si el remitente edita el formulario después de la vista previa, send() se detiene con "The batch or the fee changed" y el remitente vuelve a ver la vista previa.
Paso 6: Registra el lote
Guarda cada lote en tu backend antes de que el remitente lo firme y nunca lo sobrescribas. Conserva:
- tu propio ID de lote
- la red y el chain ID
- la dirección del remitente
- la lista de destinatarios y los montos exactos en unidades base de USDT
- la dirección del socio o la dirección cero
- la comisión de procesamiento cotizada
- los hashes de las transacciones de aprobación, si las hubo
- el hash de la transacción de pago (
txid) - el estado final de cada destinatario
batchPayout() no acepta un ID de lote, así que el vínculo entre tu lote y su transacción existe solo en tu base de datos. Úsalo para evitar duplicados: si una transacción sigue pendiente, sigue su txid y no vuelvas a enviar el mismo lote.
Paso 7: Verifica cada pago
Un hash de transacción solo muestra que el lote se envió. Un recibo exitoso o un evento BatchPayout tampoco prueban que todos los destinatarios cobraron: si falla el pago a uno, los demás no necesariamente se cancelan, y el contrato lo informa con PayoutFailed y puede reembolsar al remitente con RefundSent.
Tu backend verifica cada destinatario con los logs Transfer de USDT de la transacción. El ejemplo de abajo se ejecuta en Node.js con ethers v6. Toma el lote de tu base de datos, no del navegador.
import { ethers } from 'ethers';
import { PAYOUT_ABI } from './bnb-payouts.js';
const provider = new ethers.JsonRpcProvider(process.env.BSC_RPC_URL);
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0x55d398326f99059fF775485246999027B3197955';
const tokenEvents = new ethers.Interface([
'event Transfer(address indexed from, address indexed to, uint256 value)'
]);
const payoutEvents = new ethers.Interface(PAYOUT_ABI);
export async function verifyPayout(batch) {
const receipt = await provider.getTransactionReceipt(batch.txid);
if (!receipt) return { status: 'pending' };
if (receipt.status !== 1) return { status: 'failed' };
if (receipt.to?.toLowerCase() !== PAYOUT_ADDRESS.toLowerCase() ||
receipt.from.toLowerCase() !== batch.sender.toLowerCase()) {
return { status: 'review', reason: 'Unexpected sender or contract.' };
}
const finalized = await provider.getBlock('finalized');
if (!finalized || receipt.blockNumber > finalized.number) return { status: 'pending' };
const received = new Map();
const failed = [];
let refunded = 0n;
for (const log of receipt.logs) {
const source = log.address.toLowerCase();
if (source === USDT_ADDRESS.toLowerCase()) {
const event = tokenEvents.parseLog(log);
if (event?.name !== 'Transfer') continue;
const to = event.args.to.toLowerCase();
received.set(to, (received.get(to) ?? 0n) + event.args.value);
} else if (source === PAYOUT_ADDRESS.toLowerCase()) {
const event = payoutEvents.parseLog(log);
if (event?.name === 'PayoutFailed') failed.push(...event.args.recipients);
if (event?.name === 'RefundSent') refunded += event.args.amount;
}
}
const expected = new Map();
batch.recipients.forEach((address, i) => {
const key = address.toLowerCase();
expected.set(key, (expected.get(key) ?? 0n) + BigInt(batch.amounts[i]));
});
const results = [...expected].map(([address, amount]) => ({
address,
expected: amount.toString(),
received: (received.get(address) ?? 0n).toString(),
paid: received.get(address) === amount
}));
return {
status: results.every((result) => result.paid) ? 'paid' : 'partial',
results,
failed,
refunded: refunded.toString()
};
}
Marca como completados solo los destinatarios con paid: true. Para los demás, concilia los eventos PayoutFailed y RefundSent y revisa el saldo del remitente antes de pagarles en un lote nuevo. Nunca reenvíes un lote completo de forma automática.
Esta verificación cubre las transferencias a los destinatarios. En producción, tu backend también compara los datos de entrada de la transacción con el lote guardado, revisa los eventos del socio y de la comisión, y maneja los casos en que el proveedor RPC no está disponible o no devuelve datos de finalidad: deja el lote pendiente y vuelve a intentarlo.
Notas importantes
- Nunca pidas a los remitentes claves privadas ni frases semilla. Todas las firmas ocurren en la billetera del remitente.
- Nunca pidas por defecto una aprobación ilimitada de USDT.
- Antes de cada firma, muestra la dirección del contrato de pagos, los destinatarios, la comisión de procesamiento y la estimación de la comisión de red.
- La billetera es el último paso de aprobación. Verificar el resultado es responsabilidad de tu aplicación.
- Las transacciones confirmadas en la blockchain no se pueden cancelar ni revertir.
Si algo sale mal
| Problema | Causa | Qué hacer |
|---|---|---|
| "Install and unlock MetaMask" | No hay una billetera EIP-1193 en el navegador o está bloqueada | Pide al remitente que instale o desbloquee la billetera. |
| "Select BNB Smart Chain in your wallet" | La billetera está en otra red | Pide al remitente que cambie a BNB Smart Chain y vuelva a conectarse. No pidas ninguna firma en otra red. |
| El remitente rechaza la conexión, la aprobación o el pago | El remitente canceló la solicitud en la billetera | No envíes el lote y muestra un mensaje claro. |
| "Invalid recipient address" o "Invalid USDT amount" | Una fila del formulario tiene un error | Bloquea la vista previa y el envío hasta que el remitente corrija ese destinatario. |
| "Not enough USDT in the sender wallet" | El saldo es menor que los pagos más la comisión | Muestra el total necesario y los BNB necesarios para las comisiones de red. |
| La aprobación sigue pendiente | La transacción de aprobación aún no está confirmada | Espera la confirmación. Nunca des por hecha una aprobación solo por su hash de transacción. |
| La transacción de pago sigue pendiente | La transacción aún no está en un bloque finalizado | Sigue el txid original. No vuelvas a transmitir el mismo lote. |
| La transacción fue exitosa, pero un destinatario no tiene USDT | El pago a ese destinatario falló | Marca como completadas solo las transferencias verificadas. Concilia los destinatarios fallidos y cualquier reembolso antes de un lote nuevo. |
| "The batch or the fee changed" | El formulario, la comisión o la configuración del socio cambiaron después de la vista previa | Vuelve a mostrar la vista previa y pide al remitente que revise los nuevos totales. |
| "The payout contract is paused" | Los pagos están detenidos temporalmente en el contrato | No envíes. Inténtalo más tarde. |
Relacionado
- Enviar pagos cripto no custodiales — cómo funcionan los pagos no custodiales
- Integra pagos en USDT ERC-20 en Ethereum — el mismo formulario de pagos en Ethereum
- Integra pagos en USDT TRC-20 en TRON — el mismo formulario de pagos en TRON con TronLink
- Enviar pagos desde tu propia billetera — cómo los proyectos hacen pagos por lotes desde una billetera que controlan
- Documentación de ethers.js v6 — la biblioteca que usan los ejemplos