개발자로 시작하기

미니 앱에서 앱을 하나 만들고 API 토큰을 한 번 복사해 두면, 바로 API를 부를 수 있어요. 설정은 전부 더보기 → Merchant API에 있어요.

순서

1. 더보기 → Merchant API를 열고 앱 만들기를 선택하세요.
2. 앱 이름(예: “내 상점”)을 넣고, 원하면 **웹훅 URL (선택)**도 적어요.
3. 양식의 약관에 동의하고 앱 만들기를 누르세요. 요청이 나오면 PIN이나 생체 인증으로 확인하세요. 앱을 만들면 Merchant API 이용약관에 동의한 거예요. API를 무엇에 써도 되고 무엇에 쓰면 안 되는지 정해 둔 약관이에요.
4. API 토큰을 바로 복사하세요. 한 번만 보여 주고 다시는 보여 주지 않아요. 서버에는 해시만 남아요.
5. 첫 요청을 보낼 때 TgPayCrypto-API-Token 헤더에 토큰을 담아요.

첫 호출

클라이언트가 바라볼 API 기본 주소는 https://app.tgpaycrypto.com/pay/api예요. 먼저 getMe를 불러서 토큰이 통하는지 확인해 보세요. getBalance는 앱 잔액을, getCurrencies는 쓸 수 있는 자산 목록을 돌려줘요.

읽기 메서드는 GET이에요. createInvoice, transfer, createCheck, deleteInvoice, deleteCheck 같은 쓰기 메서드는 POST만 받아요. 파라미터는 JSON 본문, form-urlencoded, 쿼리 파라미터로 보낼 수 있어요. 금액과 멱등키가 URL 접근 로그에 남지 않도록 요청 본문으로 보내는 편이 좋아요.

테스트넷

먼저 테스트넷에서 연동을 만들어 보세요. API도 미니 앱도 똑같고, 테스트 코인에는 실제 가치가 없어요.

	메인넷	테스트넷
봇	@tgpaycryptobot	@tgpaycrypto_testnet_bot
API 기본 주소	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
MCP 서버	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

앱과 토큰은 따로 있어요. 테스트넷 토큰은 메인넷에서 안 통하고, 반대도 마찬가지예요. 테스트 코인이 필요하면 테스트넷 미니 앱을 열고 홈 화면에서 테스트 코인 받기를 누르세요. 테스트 자산 묶음이 일반 입금처럼 반영되며 비활성 네트워크의 자산은 제외해요. 앱에서 지급된 자산과 다시 요청할 수 있는 시점을 확인할 수 있어요. 두 번째 Telegram 계정을 테스트 청구서를 결제하는 고객으로 사용할 수도 있어요.

입금과 출금은 실제 블록체인 전송 없이 모의로 처리돼요. 테스트넷 입금 주소로 실제 자산을 보내지 마세요. API 규격은 같지만 이용 가능한 기능, 시세, 한도는 메인넷과 다를 수 있어요. 준비가 끝나면 @tgpaycryptobot에서 운영용 앱을 만들고 기본 URL을 바꾸세요.

앱 관리하기

Merchant API에서 앱을 열면 앱 ID와 잔액을 볼 수 있어요. 다음 작업도 할 수 있어요.

• 웹훅 주소를 설정하거나 바꾸기 — 웹훅에서 주소를 적고 저장하면 돼요.
• 추가 웹훅 이벤트 고르기 — 웹훅 섹션의 추가 웹훅 이벤트 스위치로 선택해요. invoice_paid 말고 다른 이벤트도 받고 싶을 때 켜요(웹훅 레퍼런스).
• API가 지급할 수 있는 사람 좁히기 — 지급 설정의 API로 지급에서 정해요. 새 앱은 모든 사용자로 설정돼 있어요. 목록에 있는 사람만으로 바꾸고 받는 사람을 목록에 올리거나, 연동이 사람에게 돈을 보낼 일이 없다면 끄기로 바꿔 두세요. 토큰이 새어 나갔을 때를 대비한 안전장치예요(지급 모드를 보세요).
• 권한 제한 토큰 만들기 — 접근 권한과 토큰을 열고 권한 제한 토큰에서 고른 권한만 쓸 수 있는 API 토큰을 더 만들 수 있어요(API 레퍼런스).
• 토큰 새로 발급 — 접근 권한과 토큰에서 새 토큰을 만들고 예전 토큰은 그 자리에서 못 쓰게 해요. 토큰이 새어 나갔을 때 쓰면 돼요. 새 토큰도 만들 때처럼 한 번만 보여 줘요.
• 삭제 — 먼저 사용 가능 잔액을 지급해야 해요. 그렇지 않으면 app_has_balance로 거절돼요. 아직 받지 않은 송금 링크와 대기 중인 지급도 삭제 전에 정리하세요. 앱은 목록에서 사라지고 토큰은 사용할 수 없게 되지만 결제 내역은 보존돼요.

웹훅

웹훅 주소를 저장해 두면, 서명한 JSON 본문을 그 주소로 POST해 드려요.

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

서명은 TgPayCrypto-API-Signature 헤더에 들어 있어요(TgCryptoPay-API-Signature와 Crypto-Pay-API-Signature도 호환용 별칭이에요). 원본 본문을 그대로 HMAC-SHA256으로 서명하고, 키는 기본 API 토큰의 SHA-256이에요. 페이로드를 믿기 전에 서명부터 확인하세요.

전송이 실패하면 한동안 간격을 늘려 가며 다시 보내요. 다시 보낼 때도 update_id는 그대로니까, 중복 제거는 이 값으로 하고 핸들러는 여러 번 불려도 괜찮게 만들어 주세요.

웹훅 URL을 설정했다면 invoice_paid는 별도 구독 설정 없이 보내요. 만료된 청구서, 받아 간 송금 링크, 환불, 구독 이벤트 같은 나머지는 추가 웹훅 이벤트 스위치로 원할 때만 켜요. 전체 목록과 페이로드 모양, 재전송 일정은 웹훅 레퍼런스에 있어요.

⚠️ 토큰은 개인 키처럼 다뤄 주세요

이 토큰으로 앱 잔액에서 돈을 내보낼 수 있어요. 서버에만 두고 모바일 앱이나 프런트엔드 번들, 커밋되는 설정 파일에는 넣지 마세요. 새어 나갔는지 애매하면 그냥 새로 발급하세요. 발급은 바로 되고 비용도 안 들어요. 그리고 서버마다 필요한 권한만 주세요. invoices 권한만 있는 제한 토큰은 청구서를 만들고 삭제할 수 있지만, 송금하거나 송금 링크를 만들거나 환불할 수는 없어요.