Merchant API란?
Merchant API는 사업자와 봇을 위한 결제 API예요. 앱을 만들고 API 토큰을 받으면, 내 코드에서 바로 Telegram 사용자에게 청구서를 보내고, 대금을 지급하고, 잔액을 확인할 수 있어요.
사용자가 쓰는 그 제품의 개발자 쪽 얼굴이에요. API로 만든 청구서는 사용자가 잔액으로 한 번에 결제하는 바로 그 청구서예요.
무엇을 할 수 있나요?
- 청구서 — 결제를 요청해요. 코인 금액을 고정해도 되고, 법정화폐로 값을 매겨도 되고, 내는 사람이 직접 넣는 열린 금액으로 둬도 돼요. 링크를 보내면 결제되는 순간 서명된 콜백이 와요.
- 환불 — 결제된 청구서의 금액을 전부, 또는 일부만 돌려줘요. 익명으로 결제한 사람에게도 보낼 수 있어요.
- 송금 — 앱 잔액에서 Telegram 사용자에게 코인을 보내요. 하나씩 보내도 되고, 최대 100건까지 묶어서 보내도 돼요.
- 송금 링크 — 앱 잔액으로 만들어 두면, 링크를 받은 사람이 받아 갈 수 있어요.
- 구독 — 정기 결제예요. 사용자가 한 번 승인하면 주기마다 자동으로 청구돼요.
- 잔액, 통화, 시세, 통계 — 내 장부를 맞출 때 쓰는 읽기 전용 엔드포인트예요.
이렇게 맞물려요
- 내 앱에는 개인 지갑과 별개인 잔액이 있어요.
- 사용자가 결제한 청구서는 그 앱 잔액으로 들어와요.
- 송금과 송금 링크는 거기서 빠져나가요.
- 중요한 이벤트는 모두 서명된 webhook으로 내 서버에 보내 드려요.
결제는 체인이 아니라 앱 안에서 끝나요. 네트워크 수수료도 없고, 컨펌을 기다릴 일도 없고, 들어온 자산은 바로 쓸 수 있어요. 내는 사람이 외부 지갑에서 채워 넣어도 돼요. 입금이 그 사람 지갑에 도착하면 청구서가 알아서 결제되고, 내 쪽에서 보기에는 다른 결제와 똑같아요.
Crypto Bot과 호환돼요
이 API는 일부러 Crypto Bot의 API를 그대로 따라가요. 메서드 이름도,
{ok, result} 응답 형식도, 소수점 문자열로 오가는 금액도, webhook 서명
방식도 같아요. 이미 Crypto Bot으로 붙여 둔 연동이 있다면 기본 URL과 토큰만
바꾸면 돼요. 요청과 응답 모양은 달라지지 않아요.
토큰 헤더는 TgPayCrypto-API-Token이고, Crypto-Pay-API-Token도 별칭으로
받아 줘요. 그래서 쓰던 클라이언트 라이브러리를 고치지 않아도 그대로 돌아가요.
⚠️ API 토큰은 돈을 쓸 수 있는 열쇠예요
토큰을 가진 사람은 누구나 앱 잔액을 빼 갈 수 있어요. 서버에만 두고 클라이언트 앱이나 저장소에는 넣지 마세요. 새어 나갔다 싶으면 그 자리에서 새로 발급하세요. 전체 권한이 필요 없는 서버에는 실제로 쓰는 권한만 담은 권한 제한 토큰을 만들어 주면 돼요. API 레퍼런스를 보세요.
다음 글
이 문서가 도움이 됐나요?
의견 고마워요.