개발자로 시작하기

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

순서

1. 더보기 → Merchant API를 열어요.
2. 앱 이름(예: “내 상점”)을 넣고, 원하면 Webhook URL도 적어요.
3. 앱 만들기를 눌러요.
4. API 토큰을 바로 복사하세요. 한 번만 보여 주고 다시는 보여 주지 않아요. 서버에는 해시만 남아요.
5. 첫 요청을 보낼 때 TgCryptoPay-API-Token 헤더에 토큰을 담아요.

첫 호출

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

읽기 메서드는 GET이에요. 돈이 움직이는 메서드(createInvoice, transfer, createCheck와 각각의 삭제 메서드)는 일부러 POST만 받아요. 금액과 멱등키가 접근 로그에 남으면 안 되니까요. 파라미터는 JSON 본문, form-urlencoded, 쿼리 파라미터 중 아무 방식으로나 보내도 돼요.

앱 관리하기

Merchant API 화면의 앱 카드마다 앱 ID와 잔액이 보이고, 여기서 이런 걸 할 수 있어요.

• webhook 주소를 설정하거나 바꾸기 — 적고 저장하면 돼요.
• 추가 webhook 이벤트 고르기 — webhook 주소를 저장하고 나면 추가 webhook 이벤트 스위치가 나타나요. invoice_paid 말고 다른 이벤트도 받고 싶을 때 켜요(webhook 레퍼런스).
• 권한 제한 토큰 만들기 — 권한 제한 토큰에서 고른 권한만 쓸 수 있는 API 토큰을 더 만들 수 있어요(API 레퍼런스).
• 토큰 새로 발급 — 새 토큰을 만들고 예전 토큰은 그 자리에서 못 쓰게 해요. 토큰이 새어 나갔을 때 쓰면 돼요. 새 토큰도 만들 때처럼 한 번만 보여 줘요.
• 삭제 — 그 앱으로는 더 이상 인증이 안 되지만, 잔액과 결제 내역은 그대로 남아요. 앱을 지워도 돈이 사라지지 않아요.

Webhook

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

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

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

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

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

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

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