Telegram 봇의 코인 결제: 청구서, 웹훅, 지급
Merchant API는 봇과 서비스를 위한 TgPay Crypto 결제 API예요. 앱과 토큰을 만들고 코드로 청구서를 발행해 서명된 결제 웹훅을 받아요. 호환되는 MCP 에이전트가 연동을 도울 수도 있어요. 지갑 잔액으로 결제하면 서비스 안에서 처리해요. 블록체인으로 결제하면 선택한 네트워크의 컨펌이 필요해요.
API 기본 주소: app.tgpaycrypto.com/pay/api · 테스트넷: testnet.tgpaycrypto.com
토큰부터 첫 결제까지 네 단계
청구서를 만들고 링크를 보여준 뒤 결제 이벤트를 기다리세요.
앱 만들기
봇에서 더보기 → Merchant API를 열고 이름과 웹훅 URL을 입력하세요. 토큰은 한 번만 표시되니 서버에 보관하세요.
청구서 만들기
createInvoice에 POST 요청으로 코인 또는 법정화폐 금액, 설명, 기한을 보내요. 응답에 결제 링크가 포함돼요.
결제 링크 보여주기
봇의 버튼이나 링크에서 지갑 잔액으로 결제해요. 큰 금액은 PIN이나 Face ID로 확인해요.
웹훅 처리하기
서버가 HMAC-SHA256으로 서명된 invoice_paid를 받아요. 서명을 검증하고 update_id로 중복을 제거한 후 상품을 제공하세요.
AI 에이전트가 연동을 준비해요
Merchant API는 MCP 서버를 제공해요. 호환되는 에이전트 클라이언트에 연결하면 에이전트가 문서를 읽고, 앱 생성을 요청하고, 웹훅을 설정하고, 연동 코드 작성을 도울 수 있어요. 앱은 Telegram에서 승인하고 결과를 검토한 뒤 테스트하세요.
- 단계 1
에이전트에게 요청 보내기
계정이나 워크스페이스에서 원격 MCP를 사용할 수 있는 에이전트 클라이언트를 이용하세요. 요청문은 앱의 더보기 → Merchant API → AI 에이전트 연결에도 있어요.
- 단계 2
Telegram에서 앱 승인
에이전트가 t.me 링크를 제공해요. 봇에 표시된 요청을 확인하고 승인하세요. 링크는 한 번만 유효하며 승인 전에는 앱을 만들지 않아요.
- 단계 3
연동 완료 후 테스트
에이전트는 제한된 토큰을 받아 청구서, 구독 요금제, 웹훅 설정을 도와요. 웹훅 서명 키를 받으려면 앱에서 기본 토큰을 재발급하고 서버에 안전하게 보관하세요.
이 과정에서 받는 토큰은 결제받기와 웹훅 설정만 가능해요. 송금, 송금 링크 발행, 환불은 할 수 없어요. 자산을 보내는 작업에는 별도로 관리하는 권한이 필요해요.
에이전트 연결 과정은 문서에서Connect the MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the 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
원격 MCP를 지원하는 에이전트 클라이언트에서 app.tgpaycrypto.com/mcp를 연결하세요. Telegram에서 승인하면 에이전트가 앱을 만들고 연동을 도울 수 있어요. 사용 전에 결과를 검토하고 테스트하세요.
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 명세, 단계별 안내를 확인하세요.