Pular para o conteúdo principal

Integre pagamentos em USDT BEP-20 na BNB Smart Chain

Adicione ao seu site um formulário de pagamentos em massa: o remetente conecta a própria carteira, informa os destinatários e os valores em USDT, confere a taxa e assina o lote. O contrato de pagamentos da Volet.com envia USDT BEP-20 da carteira do remetente diretamente para as carteiras dos destinatários, então os fundos nunca passam por uma conta da Volet.com.

Este guia cobre a BNB Smart Chain Mainnet. Para outras redes, consulte TRON e Ethereum.

Antes de começar​

  • Carteira do remetente — MetaMask ou outra carteira de navegador compatível com EIP-1193. Os exemplos usam o MetaMask no Google Chrome.
  • Fundos na carteira do remetente — USDT BEP-20 para os pagamentos e a taxa de processamento, além de BNB para as taxas de rede. Você não precisa abastecer nenhuma carteira para criar o formulário: quem paga é o remetente, ao enviar um lote.
  • Biblioteca — ethers.js v6. Nenhum SDK da Volet.com é necessário.
  • Site — servido por HTTPS ou a partir de localhost durante o desenvolvimento.
  • Backend e banco de dados — para guardar cada lote e verificar os pagamentos.
  • Provedor RPC — um nó da BNB Smart Chain ou um serviço hospedado para a verificação no backend.

Como funciona​

  1. O remetente preenche o formulário de pagamentos no seu site: endereços dos destinatários, valores em USDT e, opcionalmente, o endereço de um parceiro.
  2. O remetente conecta a carteira. Seu site nunca precisa da chave privada dele.
  3. Seu frontend valida o lote e obtém a taxa de processamento do contrato com previewCommission().
  4. Seu site mostra o total dos pagamentos, a taxa de processamento, o total de USDT necessário e uma estimativa da taxa de rede.
  5. Quando o remetente confirma, seu frontend verifica o saldo de USDT e a permissão de gasto (allowance). Se a permissão não for suficiente, a carteira pede ao remetente que assine antes uma transação approve().
  6. Seu frontend confere de novo a taxa, a carteira, a rede e os destinatários, e então a carteira pede ao remetente que assine batchPayout().
  7. Seu backend salva o hash da transação (txid) e verifica a transferência de USDT para cada destinatário antes de marcar esse pagamento como concluído.

Se o pagamento a um destinatário falhar, os outros não são necessariamente cancelados, por isso uma transação bem-sucedida não prova que todos receberam. Consulte Etapa 7: Verifique cada pagamento.

Contrato de pagamentos​

Valor
RedeBNB Smart Chain Mainnet, chain ID 56 (0x38)
Contrato de pagamentos0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7 (BscScan)
Contrato do USDT0x55d398326f99059fF775485246999027B3197955 (Binance-Peg USDT, exibido como BSC-USD)
Casas decimais do USDT18 (1 USDT = 10^18 unidades base)
Taxa de rede paga emBNB
Endereço zero (sem parceiro)0x0000000000000000000000000000000000000000

O mesmo endereço do contrato de pagamentos também existe na Ethereum. São duas implantações diferentes e não intercambiáveis: antes de pedir uma assinatura, sempre confira o chain ID da carteira e o resultado de usdt() do contrato.

O contrato oferece estas funções:

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;

Ele emite os eventos BatchPayout, PayoutFailed, RefundSent, PartnerNotFound e CommissionTransferFailed. PayoutFailed lista os destinatários e os valores que não foram pagos.

Confira a ABI do contrato

Os exemplos desta página incluem apenas as funções e os eventos que usam. Antes de integrar, abra o contrato de pagamentos no BscScan, pegue a ABI completa na aba Contract e compare com ela as assinaturas das funções, os tipos de parâmetros e os eventos do seu código. Antes de enviar fundos reais, compare também com esta página o endereço do token retornado por usdt(), as casas decimais do token, os resultados de previewCommission() e os eventos do contrato.

Taxas​

A taxa de processamento é de 0.1 USDT por destinatário do lote, somada aos valores dos pagamentos. Por exemplo, um lote que paga 10, 20 e 30 USDT a 3 destinatários precisa de 60 USDT para os pagamentos e 0.3 USDT para a taxa: 60.3 USDT no total.

Sempre mostre ao remetente o valor atual de previewCommission(), e não uma taxa calculada no seu código.

O remetente também paga a taxa de rede da BNB Smart Chain em BNB por transação: o pagamento e, quando necessária, a aprovação.

Endereço do parceiro​

batchPayout() recebe o argumento whiteLabel para a carteira opcional de um parceiro que divide a taxa de processamento. Um lote funciona sem parceiro: passe o endereço zero.

Se houver parceiro, passe o endereço da carteira dele. getPartner() mostra se o endereço é de um parceiro ativo e qual é a participação dele em pontos-base, e previewCommissionSplit() mostra como a taxa é dividida entre a Volet.com e o parceiro. A taxa paga pelo remetente não muda: previewCommission() não depende do parceiro.

Para registrar a carteira de um parceiro, escreva para [email protected] informando o endereço da carteira e a rede.

Etapa 1: Adicione o formulário de pagamentos​

Instale o ethers.js:

npm install ethers@^6

Adicione os controles do formulário à sua página. Cada bloco data-payout-row é um destinatário; adicione ou remova blocos para mudar o número de destinatários.

<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 colocar o formulário em produção, adicione seus próprios estilos, o gerenciamento de linhas, os indicadores de progresso e o estado desabilitado dos botões.

Etapa 2: Conecte a carteira do remetente​

Crie bnb-payouts.js, um módulo do navegador, e comece-o com a configuração do contrato e a função de conexão. As etapas 3 e 4 acrescentam código ao mesmo arquivo.

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.');
}
}

Chame connect() apenas quando o remetente selecionar Connect wallet, nunca no carregamento da página. Se a carteira estiver em outra rede, peça ao remetente que mude para a BNB Smart Chain.

Etapa 3: Mostre o lote e a taxa​

Adicione as funções de validação e de pré-visualização a bnb-payouts.js. quote() transforma as linhas do formulário em argumentos do contrato em unidades base de USDT e obtém a taxa, o saldo e a permissão 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)
};
}

Mostre ao remetente total, commission e required, formatados com ethers.formatUnits(value, USDT_DECIMALS), junto com uma estimativa da taxa de rede em BNB. Não converta valores com aritmética de ponto flutuante: parseUnits() os mantém exatos.

Confira os destinatários antes de assinar

Um pagamento enviado a um endereço errado não pode ser cancelado nem devolvido. Mostre ao remetente cada endereço e cada valor antes da assinatura e aceite apenas endereços da BNB Smart Chain que possam receber USDT BEP-20.

Etapa 4: Aprove o USDT e envie o lote​

Adicione a função de envio a bnb-payouts.js. Ela verifica se nada mudou desde que o remetente revisou o lote, pede uma aprovação se a permissão de gasto não for suficiente e então envia 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 };
}

Dependendo da permissão de gasto existente, o remetente assina uma ou duas transações:

Permissão existenteTransações a assinar
Suficiente para o lotePagamento
InsuficienteAprovação, pagamento

A aprovação cobre exatamente o valor deste lote, nunca um valor ilimitado. Ela precisa ser confirmada antes da transação de pagamento; uma transação approve() não movimenta fundos.

Etapa 5: Conecte os botões​

Ligue o módulo ao formulário. As solicitações à carteira partem apenas dos cliques do remetente, e os destinatários e os valores sempre vêm do formulário.

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)));
});
}

Se o remetente editar o formulário depois da pré-visualização, send() para com "The batch or the fee changed", e o remetente faz a pré-visualização de novo.

Etapa 6: Registre o lote​

Guarde cada lote no seu backend antes que o remetente o assine e nunca o sobrescreva. Mantenha:

  • seu próprio ID do lote
  • a rede e o chain ID
  • o endereço do remetente
  • a lista de destinatários e os valores exatos em unidades base de USDT
  • o endereço do parceiro ou o endereço zero
  • a taxa de processamento cotada
  • os hashes das transações de aprovação, se houver
  • o hash da transação de pagamento (txid)
  • o status final de cada destinatário

batchPayout() não aceita um ID de lote, então o vínculo entre o seu lote e a transação dele existe apenas no seu banco de dados. Use-o para evitar duplicidades: se uma transação ainda estiver pendente, acompanhe o txid dela e não envie o mesmo lote de novo.

Etapa 7: Verifique cada pagamento​

Um hash de transação mostra apenas que o lote foi enviado. Um recibo bem-sucedido ou um evento BatchPayout também não provam que todos os destinatários receberam: se o pagamento a um deles falhar, os outros não são necessariamente cancelados, e o contrato informa isso com PayoutFailed e pode reembolsar o remetente com RefundSent.

Seu backend confere cada destinatário com os logs Transfer de USDT da transação. O exemplo abaixo roda em Node.js com ethers v6. Ele pega o lote do seu banco de dados, e não do 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()
};
}

Marque como concluídos apenas os destinatários com paid: true. Para os demais, concilie os eventos PayoutFailed e RefundSent e confira o saldo do remetente antes de pagá-los em um novo lote. Nunca reenvie um lote inteiro automaticamente.

Essa verificação cobre as transferências aos destinatários. Em produção, seu backend também compara os dados de entrada da transação com o lote salvo, confere os eventos do parceiro e da taxa e trata os casos em que o provedor RPC está indisponível ou não retorna dados de finalidade: mantenha o lote pendente e tente de novo.

Observações importantes​

  • Nunca peça aos remetentes chaves privadas ou frases-semente. Todas as assinaturas acontecem na carteira do remetente.
  • Nunca peça por padrão uma aprovação ilimitada de USDT.
  • Antes de cada assinatura, mostre o endereço do contrato de pagamentos, os destinatários, a taxa de processamento e a estimativa da taxa de rede.
  • A carteira é a última etapa de aprovação. Verificar o resultado é responsabilidade da sua aplicação.
  • Transações confirmadas na blockchain não podem ser canceladas nem revertidas.

Se algo der errado​

ProblemaCausaO que fazer
"Install and unlock MetaMask"Não há carteira EIP-1193 no navegador ou ela está bloqueadaPeça ao remetente que instale ou desbloqueie a carteira.
"Select BNB Smart Chain in your wallet"A carteira está em outra redePeça ao remetente que mude para a BNB Smart Chain e se conecte de novo. Não peça nenhuma assinatura em outra rede.
O remetente recusa a conexão, a aprovação ou o pagamentoO remetente cancelou a solicitação na carteiraNão envie o lote e mostre uma mensagem clara.
"Invalid recipient address" ou "Invalid USDT amount"Uma linha do formulário tem um erroBloqueie a pré-visualização e o envio até o remetente corrigir esse destinatário.
"Not enough USDT in the sender wallet"O saldo é menor que os pagamentos mais a taxaMostre o total necessário e os BNB necessários para as taxas de rede.
A aprovação ainda está pendenteA transação de aprovação ainda não foi confirmadaAguarde a confirmação. Nunca considere uma aprovação feita só pelo hash da transação.
A transação de pagamento ainda está pendenteA transação ainda não está em um bloco finalizadoAcompanhe o txid original. Não transmita o mesmo lote de novo.
A transação foi bem-sucedida, mas um destinatário não tem USDTO pagamento a esse destinatário falhouMarque como concluídas apenas as transferências verificadas. Concilie os destinatários com falha e qualquer reembolso antes de um novo lote.
"The batch or the fee changed"O formulário, a taxa ou as configurações do parceiro mudaram depois da pré-visualizaçãoFaça a pré-visualização de novo e peça ao remetente que revise os novos totais.
"The payout contract is paused"Os pagamentos estão temporariamente suspensos no contratoNão envie. Tente de novo mais tarde.