청구서로 결제 받기

청구서는 Telegram 사용자에게 대금을 청구하는 방법이에요. API로 하나 만들어 결제할 사람에게 링크를 보내세요. 결제가 성공하면 가맹점 수수료를 뺀 금액이 앱 잔액에 반영돼요.

흐름

1. 청구서를 만들어요. createInvoice에 자산과 금액을 넘겨요. 법정화폐로 값을 매겨도 되고요(아래 참고).
2. 결제할 사람에게 링크를 보내요. 응답에 들어 있는 링크예요. 열면 앱의 결제 화면으로 이동해요.
3. 상대가 확인해요. 잔액에서 바로 결제되고 네트워크 수수료도 없어요. 해당 옵션이 제공되면 부족한 잔액을 외부 지갑에서 충전해 결제할 수 있어요. 자동 결제에는 결제 기한 전 충분히 반영된 잔액이 필요하며 나가는 결제가 제한되지 않아야 해요. 입금만으로 청구서 결제를 확인할 수는 없어요.
4. 알림이 와요. 웹훅 URL을 설정했다면 결제 후 invoice_paid 이벤트가 전송 대기열에 들어가요. 수수료를 뺀 금액이 앱 잔액에 반영돼요.
5. 주문을 처리하세요. 먼저 웹훅 서명을 검증하고 청구서를 주문과 대조한 뒤 paid 상태인지 확인하세요. getInvoices로 상태를 확인할 수도 있어요. 추가 블록체인 컨펌은 필요하지 않아요.

웹훅 대신 직접 조회하고 싶다면 getInvoices로 청구서와 현재 상태를 가져올 수 있어요. 빠른 쪽은 웹훅이고, 조회는 보조 수단이에요.

법정화폐로 값 매기기

청구서 금액은 코인으로 매길 수도 있고, 법정화폐로 매기면서 받을 자산 목록을 정해 둘 수도 있어요. 그러면 내는 사람이 가진 자산 중에서 골라 결제하고, 결제 시점 시세로 환산돼요. 카탈로그 가격이 실제 통화로 적혀 있는 상점이라면 보통 이쪽을 골라요.

가격을 딱 고정해서 보여 주고 싶다면 rate_lock_seconds로 만들 때의 환산 시세를 정해진 시간 동안 묶어 둘 수 있어요. 내는 사람은 묶인 금액 그대로 보고, 그동안의 시세 변동은 내가 떠안아요. 자세한 건 청구서 레퍼런스에 있어요.

swap_to를 넣으면 들어온 결제를 하나의 자산으로 바꿔서 받을 수도 있어요. 교환이 가능할 때 적용되며 실패해도 원래 자산으로 결제는 완료돼요. is_swapped와 swapped_* 필드를 확인하세요.

알아 두면 좋은 옵션

• description — 결제 화면에서 내는 사람에게 보여요.
• hidden_message — 결제한 뒤에만 보여요. 코드나 키, 링크를 따로 보내는 채널 없이 전달할 때 써요.
• payload — 내가 넣는 아무 문자열이고, 웹훅에 그대로 되돌아와요. 주문 번호를 여기 넣으면 돼요.
• expires_in — 이 시간이 지나면 더 이상 결제할 수 없어요.
• paid_btn_name / paid_btn_url — 결제한 사람에게 보여 줄 버튼이에요. 내 봇이나 채널, 상품 페이지로 돌려보낼 때 써요.
• open_amount — 금액을 정해 두지 않고, 내는 사람이 결제할 때 직접 넣어요. 후원이나 팁에 어울려요.

설명, 숨긴 콘텐츠, 결제 후 버튼은 콘텐츠 승인 전까지 결제자에게 숨겨질 수 있어요. 생성 직후 바로 보일 것이라고 가정하지 마세요.

아직 결제되지 않은 청구서는 deleteInvoice로 취소할 수 있어요.

환불

refundInvoice는 실제로 결제한 코인 금액을, 또는 그중 일부만 앱 잔액에서 결제한 사람에게 돌려줘요. 익명으로 결제한 사람에게도 보낼 수 있고, 그 사람이 누구인지는 드러나지 않아요. 부분 환불은 원래 결제한 코인 금액까지 누적되고, 청구서의 refunded_amount에 기록돼요. 법정화폐 청구서는 액면가가 아니라 paid_asset과 paid_amount를 사용해요. 자동 교환을 거쳤더라도 앱 잔액에 원래 결제 자산이 충분해야 해요. spend_id를 넘기면 응답이 늦어 다시 보내도 두 번 환불되지 않고 원래 결과가 그대로 돌아와요. 서비스 수수료는 환불되지 않아요.

⚠️ 주문을 처리하기 전에 웹훅 서명을 확인하세요

내 웹훅 주소로는 누구나 POST를 보낼 수 있어요. TgPayCrypto-API-Signature 헤더부터 확인하세요. 원본 요청 본문을 HMAC-SHA256으로 서명한 값이고, 키는 기본 API 토큰의 SHA-256이에요. 서명이 맞을 때만 결제를 진짜로 받아들이고, update_id로 중복을 걸러서 재전송 때문에 주문이 두 번 나가지 않게 해 주세요.