텔레그램 봇에서 USDT 결제를 받는 방법
텔레그램 봇은 디지털 상품을 팔기에 가장 좋은 곳 가운데 하나이고, 기존 방식의 결제 화면을 끼워 넣기에는 가장 나쁜 곳 가운데 하나입니다. 카드 입력 양식도, 자연스럽게 느껴지는 호스팅 결제 페이지도 없고, 사용자는 브라우저로 쫓겨나는 것을 싫어합니다. 단순한 REST API를 제공하는 암호화폐 결제 게이트웨이가 훨씬 잘 맞습니다. 봇이 청구서를 만들고, 결제 정보를 메시지로 보내고, 돈이 도착했다는 웹훅이 오면 반응합니다.
시작하기 전에 필요한 것
- @BotFather에서 받은 봇 토큰.
- HTTPS 요청을 받을 수 있는 서버. 봇의 백엔드와 웹훅 수신부는 같은 애플리케이션이어도 됩니다.
- 2단계 인증을 켠 VisualPay 계정, 생성된 가맹점, 패널에서 복사한 가맹점 API 키. 가입과 첫 가맹점은 무료이며 먼저 통과해야 할 본인 확인이 없습니다.
- 받으려는 코인과 네트워크마다 본인이 관리하는 지갑 주소. 가맹점에 등록해 둡니다.
흐름의 전체 모습
코드를 쓰기 전에 누가 무엇을 하는지 정확히 해 두는 것이 좋습니다. 봇 결제에서 돈이 새는 원인이 바로 여기에 있기 때문입니다.
- 사용자가 봇에서 상품을 고릅니다.
- 백엔드가(클라이언트가 아닙니다) 게이트웨이를 호출해 거래를 생성합니다.
- 봇이 결제 주소, 정확한 USDT 수량, 마감 시간을 메시지로 보냅니다.
- 사용자가 자기 지갑에서 결제합니다.
- 게이트웨이가 결제를 감지하고 웹훅을 호출합니다.
- 백엔드가 상태를 검증하고, 주문을 결제 완료로 표시하고, 봇이 상품을 전달하게 합니다.
6단계를 일으키는 것은 5단계이지 사용자의 행동이 아니라는 점에 주목하세요. 대화창의 "결제했어요" 버튼은 상태를 다시 확인하라는 신호로는 괜찮지만, 상품을 내주는 근거가 되어서는 안 됩니다.
1단계: 어떤 네트워크인지 묻기
USDT는 여러 체인에 존재하고 서로 호환되지 않습니다. TRC20 USDT를 ERC20 주소로 보내면 사라집니다. 그러니 네트워크는 자유 입력이 아니라 인라인 키보드로 명시적으로 고르게 하세요.
{
"inline_keyboard": [
[{ "text": "USDT · TRC20 (Tron)", "callback_data": "pay:USDT:trc20" }],
[{ "text": "USDT · BEP20 (BSC)", "callback_data": "pay:USDT:bep20" }],
[{ "text": "USDT · ERC20 (Ethereum)", "callback_data": "pay:USDT:erc20" }]
]
}
실용적인 팁 하나: TRC20을 맨 위에 두세요. Tron의 네트워크 수수료는 충분히 낮아서 소액 구매에 대체로 가장 부담이 적고, 봇에서 팔리는 것은 대부분 소액 상품입니다.
2단계: 서버에서 거래 생성하기
콜백 쿼리가 도착하면 백엔드가 청구서를 만듭니다. API 키는 헤더에 넣고 절대 서버 밖으로 내보내지 않습니다.
const res = await fetch(
'https://visualpay.net/api/v1/merchant/transaction/create',
{
method: 'POST',
headers: {
'x-api-key': process.env.VISUALPAY_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
currency_symbol: 'USDT',
network_code: 'trc20',
amount_usd: 25.5,
ttl: 20,
order_id: order.id,
comment: `Telegram user ${ctx.from.id}`,
}),
}
);
const tx = await res.json();
그대로 베끼기보다 한 번 생각해 볼 만한 필드가 몇 가지 있습니다.
ttl은 분 단위 결제 가능 시간이면서 환율이 고정되는 시간입니다. 봇에는 20분이 무난한 기본값입니다. 지갑 앱을 열기에 충분하고, 가격 변동 노출을 제한하기에는 충분히 짧습니다.order_id는 직접 정하는 식별자입니다. 텔레그램 사용자 및 채팅과 함께 저장해 두어야 웹훅이 올바른 대화를 다시 찾아갈 수 있습니다.comment는 패널에 표시되는 자유 텍스트입니다. 사용자가 "결제했는데 아무것도 못 받았어요"라고 할 때 지원 업무에 유용합니다.
반환된 추적 코드는 주문과 연결해 즉시 저장하세요. 나중에 결제를 조회할 때 쓰는 값입니다.
3단계: 청구서를 메시지로 보여 주기
게이트웨이가 리디렉션하지 않고 결제 데이터를 돌려주므로 자연스러운 형태로 보여 줄 수 있습니다. 금액과 주소를 고정폭으로 넣어 텔레그램에서 탭 한 번으로 복사되게 하고, 주소가 줄바꿈으로 끊기지 않게 하세요.
정확히 다음 금액을 보내세요:
1580.70 USDT
네트워크: TRC20 (Tron)
받는 주소:
TXk...c72E
⏱ 20분 후 만료됩니다.
두 가지를 더하면 효과가 확실합니다. 모바일 사용자가 다른 기기로 스캔할 수 있도록 QR 코드를 첨부하세요. 그리고 상태 엔드포인트를 호출하는 "결제 확인" 버튼을 추가하세요. 상품을 내주기 위한 버튼이 아니라, 조급한 사용자가 고객 지원에 메시지를 보내는 대신 누를 것을 주기 위한 버튼입니다.
4단계: 웹훅 처리하기
주문이 실제로 완료되는 곳입니다. 엔드포인트는 HTTPS여야 하고, 단조롭고 방어적으로 작성해야 합니다.
app.post('/webhooks/visualpay', async (req, res) => {
// 1. 게이트웨이가 기다리지 않도록 빠르게 응답합니다.
res.sendStatus(200);
const { tracking_code } = req.body;
// 2. 페이로드를 믿지 말고 서버에서 다시 검증합니다.
const status = await verifyWithGateway(tracking_code);
if (status !== 'confirmed') return;
// 3. 멱등성: 웹훅은 두 번 이상 도착할 수 있습니다.
const order = await orders.findByTrackingCode(tracking_code);
if (!order || order.fulfilled) return;
await orders.markFulfilled(order.id);
await bot.telegram.sendMessage(order.chat_id, '결제가 확인되었습니다. 상품을 보내 드립니다: …');
});
번호가 붙은 주석 세 개가 핵심 전부입니다. 빠르게 응답하세요. 웹훅 처리가 느리면 재시도가 일어납니다. 요청 본문을 믿지 말고 상태 엔드포인트로 다시 검증하세요. API 호출 한 번이 더 들지만 위조 공격 한 부류가 통째로 사라집니다. 멱등하게 만드세요. 재시도된 웹훅이 상품을 두 번 전달하는 것은 운영 환경에서 실제로 일어나는 버그입니다.
5단계: 순조롭지 않은 경우 처리하기
봇의 성패는 일이 깔끔하게 풀리지 않을 때 어떻게 대응하느냐에 달려 있습니다.
- 만료. 결제 없이 시간이 끝났습니다. 청구된 것은 없습니다. 메시지를 수정해 이를 알리고, 현재 환율로 새 거래를 생성하는 "다시 시도" 버튼을 제공하세요.
- 부족 입금. 가맹점에 설정한 부족분 허용 오차 안이면 결제가 처리되고 입금액은 실제 도착한 금액으로 다시 계산됩니다. 그 범위를 벗어나면 얼마가 도착했고 얼마가 필요했는지 사용자에게 분명히 알려 주세요.
- 초과 입금. 승인되고 초과 입금으로 기록됩니다. 정책을 미리 정해 두고(차액을 계정 잔액에 적립하거나 수동으로 환불) 사용자가 결제하기 전에 봇에서 안내하세요.
- 늦은 결제. 만료 1분 뒤에 결제하는 사용자가 있습니다. 재확인 엔드포인트는 만료되거나 취소된 거래의 온체인 결제를 다시 검증하므로, 지원 문의로 번지지 않고 복구할 수 있습니다.
정산받기
VisualPay는 비수탁형이므로 확인된 결제 대금이 제공업체 잔액에 머물며 출금을 기다리지 않습니다. 네트워크별 잔액이 정산 기준 금액을 넘으면 자금이 등록한 지갑 주소로 자동 전송되며, 보통 1분 안에 끝나고 체인 자체의 네트워크 수수료만 차감됩니다.
진지하게 챙겨야 할 보안 사항
- API 키는 서버의 환경 변수에 둡니다. 봇의 클라이언트 코드에도, 저장소에도, 메시지에도 절대 넣지 않습니다.
- 웹훅 엔드포인트는 HTTPS여야 하고, 추측하기 쉬운 경로가 아니라 알기 어려운 경로를 써야 합니다.
- 거래를 생성하는 명령에 요청 제한을 거세요. 그러지 않으면 사용자 한 명이 미결제 청구서 수백 개를 쏟아낼 수 있습니다.
- 주기적으로 대사하세요. 매일 밤 거래 목록을 불러와 자체 주문과 비교하는 작업을 돌리면 웹훅을 아예 놓친 소수의 경우를 잡아낼 수 있습니다.
이 패턴이 봇에 잘 맞는 이유
설치할 플러그인도, 최신 상태로 유지할 SDK도, 대화를 끊는 리디렉션도 없습니다. 봇은 봇으로 남습니다. 청구서가 나타나고, 결제되고, 전달된 상품으로 바뀌는 하나의 메시지 스레드입니다. 게이트웨이가 하는 모든 일(환율 고정, 주소 발급, 체인 모니터링, 정산)은 HTTP 호출 두 번과 웹훅 하나 뒤에서 이루어집니다.
오늘부터 USDT와 USDC 결제를 받아 보세요
KYC 없이 시작하고, 결제 화면은 내 사이트에 두고, 대금은 내 지갑으로 정산받으세요. 가입과 첫 가맹점 등록은 무료입니다.