Merchant API란?
Merchant API는 사업자와 봇을 위한 결제 API예요. 앱을 만들고 API 토큰을 받으면, 내 코드에서 바로 Telegram 사용자에게 청구서를 보내고, 대금을 지급하고, 잔액을 확인할 수 있어요.
사용자가 쓰는 앱의 기능을 개발자가 연동할 수 있도록 제공해요. API로 만든 청구서는 사용자가 잔액으로 한 번에 결제하는 바로 그 청구서예요.
무엇을 할 수 있나요?
- 청구서 — 결제를 요청해요. 코인 금액을 고정해도 되고, 법정화폐로 값을 매겨도 되고, 내는 사람이 금액을 직접 정하도록 해도 돼요. 결제자에게 링크를 보내세요. 웹훅 URL을 설정했다면 결제 후 서명된 웹훅을 받아요.
- 환불 — 결제된 청구서의 금액을 전부, 또는 일부만 돌려줘요. 익명으로 결제한 사람에게도 보낼 수 있어요.
- 송금 — 앱 잔액에서 Telegram 사용자에게 코인을 보내요. 하나씩 보내도 되고, 최대 100건까지 묶어서 보내도 돼요.
- 송금 링크 — 앱 잔액으로 누구나 받거나 지정한 수신자가 받을 수 있는 링크를 만들어요. 지급 설정이 적용돼요.
- 구독 — 정기 결제예요. 사용자가 한 번 승인하면 주기마다 자동으로 청구돼요.
- 잔액, 통화, 시세, 통계 — 내 장부를 맞출 때 쓰는 읽기 전용 엔드포인트예요.
이렇게 맞물려요
- 내 앱에는 개인 지갑과 별개인 잔액이 있어요.
- 사용자가 결제한 청구서는 그 앱 잔액으로 들어와요.
- 송금과 송금 링크는 거기서 빠져나가요.
- URL과 이벤트 구독을 설정하면 지원하는 결제 이벤트를 서명된 웹훅으로 서버에 보낼 수 있어요.
결제는 체인이 아니라 앱 안에서 끝나요. 네트워크 수수료도 없고, 컨펌을
기다릴 일도 없고, 들어온 자산은 바로 쓸 수 있어요. 해당 옵션이 제공되면 결제자는 외부 지갑에서 충전할 수도 있어요. 입금은 결제자 본인의 지갑에 반영돼요. 자동 결제에는 충분한 잔액, 나가는 거래 제한이 없는 상태, 유효한 결제 기한도 필요해요. 주문을 처리하기 전에 청구서가 paid인지 확인하세요.
Crypto Bot과 호환돼요
이 API는 일부러 Crypto Bot의 API를 그대로 따라가요. 메서드 이름도,
{ok, result} 응답 형식도, 소수점 문자열로 오가는 금액도, 웹훅 서명
방식도 같아요. 이미 Crypto Bot으로 붙여 둔 연동이 있다면 기본 URL과 토큰만
바꾼 뒤 사용하는 메서드를 레퍼런스와 대조해 테스트하세요. Crypto Bot과 마찬가지로 봇과
기본 URL이 따로 있는 테스트넷도 운영해요.
토큰 헤더의 정식 이름은 TgPayCrypto-API-Token이에요. 2026-09-07 전
이름인 TgCryptoPay-API-Token도 그대로 통하고, Crypto-Pay-API-Token도
별칭으로 받아 줘요. 그래서 쓰던 클라이언트 라이브러리를 고치지 않아도 그대로
돌아가요.
⚠️ API 토큰은 돈을 쓸 수 있는 열쇠예요
기본 토큰은 앱의 지급 모드와 한도 안에서 지급을 승인할 수 있어요. 서버에만 두고 클라이언트 앱이나 저장소에는 넣지 마세요. 새어 나갔다 싶으면 그 자리에서 새로 발급하세요. 전체 권한이 필요 없는 서버에는 실제로 쓰는 권한만 담은 권한 제한 토큰을 만들어 주면 돼요. API 레퍼런스를 보세요.
다음 글
이 문서가 도움이 됐나요?
의견 고마워요.