Telegram 봇의 코인 결제: 청구서, 웹훅, 지급
Merchant API는 봇과 서비스를 위한 TgPay Crypto 결제 API예요. 봇에서 앱과 토큰을 만들고 코드로 청구서를 발행해 결제마다 서명된 웹훅을 받아요. MCP 서버로 AI 에이전트에게 연동을 맡길 수도 있어요. 서비스 내부 결제라 네트워크 수수료나 컨펌 대기가 없어요.
API 기본 주소: app.tgpaycrypto.com/pay/api · 테스트넷: testnet.tgpaycrypto.com
토큰부터 첫 결제까지 네 단계
청구서를 만들고 링크를 보여준 뒤 결제 이벤트를 기다리세요.
앱 만들기
봇에서 더보기 → Merchant API를 열고 이름과 웹훅 URL을 입력하세요. 토큰은 한 번만 표시되니 서버에 보관하세요.
청구서 만들기
createInvoice에 POST 요청으로 코인 또는 법정화폐 금액, 설명, 기한을 보내요. 응답에 결제 링크가 포함돼요.
결제 링크 보여주기
봇에 버튼이나 링크를 넣으세요. 이용자는 지갑 잔액으로 결제해요.
웹훅 처리하기
서버가 HMAC-SHA256으로 서명된 invoice_paid를 받아요. 서명을 검증하고 update_id로 중복을 제거한 후 상품을 제공하세요.
AI 에이전트가 연동을 준비해요
Merchant API는 MCP 서버를 제공해요. URL을 주면 에이전트가 문서를 읽고, 승인을 받아 앱을 만들고, 웹훅과 코드를 준비해요. 토큰을 직접 복사할 필요 없어요.
- 단계 1
에이전트에게 요청 보내기
Claude Code, claude.ai, Claude Desktop, ChatGPT 등 MCP 클라이언트를 이용해요. 앱의 더보기 → Merchant API → AI 에이전트 연결에도 같은 요청문이 있어요.
- 단계 2
Telegram에서 앱 승인
에이전트가 t.me 링크를 제공해요. 봇에 표시된 요청을 확인하고 승인하세요. 링크는 한 번만 유효하며 승인 전에는 앱을 만들지 않아요.
- 단계 3
에이전트가 설정 완료
제한된 토큰을 받아 청구서, 구독 요금제, 웹훅을 설정해요. 웹훅 서명 키는 앱에서 직접 관리해요.
이 과정에서 받는 토큰은 결제받기와 웹훅 설정만 가능해요. 송금, 송금 링크 발행, 환불은 할 수 없어요. 자산을 보내는 작업에는 별도로 관리하는 권한이 필요해요.
에이전트 연결 과정은 문서에서Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
클라이언트 설정에서 app.tgpaycrypto.com/mcp를 MCP 서버로 추가하세요
https://testnet.tgpaycrypto.com/mcp
수수료와 한도
페이지를 만들 때의 공개 한도 목록을 기준으로 해요. 현재 적용되는 값은 앱에서 확인하세요.
Merchant API 기능
앱은 지갑과 별도 잔액을 가져요. 청구서 결제는 이 잔액에 반영되고 지급과 송금 링크는 여기서 차감돼요.
청구서와 환불
코인 고정 금액, 법정화폐 가격, 결제자가 정하는 금액을 지원해요. 익명 결제도 전액 또는 일부 환불할 수 있어요.
구독
이용자가 요금제에 한 번 동의하면 이후 주기마다 자동 결제하고 각 결제의 이벤트를 보내요.
송금과 송금 링크
앱 잔액에서 Telegram 이용자에게 지급하고, 설정한 조건을 충족하는 사람이 받을 송금 링크를 만들 수 있어요.
웹훅
invoice_paid는 항상 보내요. 청구서 만료, 송금 링크 받기, 환불, 구독 이벤트는 앱별로 켤 수 있어요.
테스트넷
@tgpaycrypto_testnet_bot에서 같은 API와 미니 앱을 이용해요. 홈 버튼으로 한 시간에 한 번 테스트 코인을 받아요.
AI 에이전트와 MCP
에이전트에게 app.tgpaycrypto.com/mcp를 전달하세요. 앱 생성, 웹훅 설정, 연동 코드를 준비해요. 앱 생성은 봇에서 승인해요.
Crypto Bot API 호환
메서드 이름, {ok, result} 형식, 웹훅 서명 방식이 호환돼요. 기본 URL과 토큰을 바꾸고 사용하는 메서드를 테스트하세요.
토큰 권한 관리
제한된 토큰, 즉시 교체, 지정 이용자만 지급하거나 지급 중지, 토큰 유출에 대비한 일일 지급 한도를 설정해요.
API 질문
토큰, 웹훅 서명, 테스트, 다른 API에서 이전하는 방법을 안내해요.
현재 정책에 따라 인증을 마쳐야 앱을 만들 수 있어요. 인증 오류가 나타나면 앱에서 본인 인증을 완료하고 다시 시도하세요.
TgPayCrypto-API-Signature 헤더는 기본 토큰의 SHA-256을 키로 사용해 요청 본문의 HMAC-SHA256을 계산한 값이에요. 원본 본문 바이트로 비교하세요. 검증 전에는 상품을 제공하거나 결제 완료로 표시하지 마세요.
Merchant API는 Crypto Bot API의 메서드, {ok, result} 형식, 소수 문자열 금액, 서명 방식을 지원해요. 기본 URL과 토큰을 바꾼 뒤 연동을 테스트하세요. Crypto-Pay-API-Token 헤더도 별칭으로 사용할 수 있어요.
테스트넷은 같은 API와 미니 앱을 사용해요. 봇은 @tgpaycrypto_testnet_bot, 기본 주소는 testnet.tgpaycrypto.com/pay/api예요. 홈 버튼으로 한 시간에 한 번 테스트용 1,000 USDT, 1,000 GRAM, 0.01 BTC를 받아요. 메인넷과 테스트넷 토큰은 서로 사용할 수 없어요.
에이전트는 제한된 토큰으로 청구서와 구독 요금제 생성, 잔액·통계 조회, 웹훅 설정을 해요. 송금, 송금 링크, 환불에는 추가 권한과 해당 기능 활성화가 필요해요.
Merchant API 공개 문서
docs.tgpaycrypto.com에서 메서드, OpenAPI 명세, 단계별 안내를 확인하세요.