Source: https://cryptanio.com/ko/wiki/crypto-payments-telegram-bot/
Language: ko

# Telegram 봇에서 암호화폐 결제 받는 방법

직접 만든 Telegram 봇의 실물 상품 주문을 Cryptanio 인보이스와 연결하고\, 결제 링크를 보내고\, 결제를 확인하는 방법입니다\. Telegram Stars와 Mini Apps의 제한도 설명합니다\.

수정일: 2026-11-14

직접 만든 Telegram 봇의 주문에 암호화폐 결제를 연결할 수 있습니다\. 서버가 Cryptanio 인보이스를 만들고\, 봇이 구매자에게 링크를 보낸 뒤\, 결제를 확인하면 주문이 접수되었다고 알려 줍니다\. 이 글에서는 인쇄 포스터와 같은 실물 상품을 판매하는 상점을 예로 들겠습니다\. 봇과 주문 처리 기능은 직접 개발해야 합니다\.

## 먼저 Telegram 규칙을 확인하세요 {#telegram}

Telegram 안에서 판매하는 디지털 상품과 서비스에는 XTR로 표시되는 Telegram Stars를 반드시 사용해야 합니다\. 예를 들어 봇 콘텐츠에 대한 유료 이용권이 여기에 해당합니다\. 외부 웹사이트 링크를 제공해도 예외가 되지 않습니다\. 이런 구매에서 Stars 대신 암호화폐 결제를 제안할 수는 없습니다\. 이러한 제한은 [Telegram Stars 문서](<https://core.telegram.org/bots/payments-stars>)에 명시되어 있습니다\.

이 가이드의 시나리오는 Mini App이 없는 일반 봇에서 실물 상품을 주문하는 경우입니다\. Mini Apps와 관련 봇에는 TON 사용을 포함해 블록체인 연동에 관한 추가 제한이 적용됩니다\. Mini App이 없는 일반 봇은 [Telegram Blockchain Guidelines](<https://core.telegram.org/bots/blockchain-guidelines>)에서 이 규칙의 적용 대상에서 명시적으로 제외됩니다\. 따라서 별도의 확인 없이 이 가이드를 Mini App에 그대로 적용할 수는 없습니다\. Telegram 규칙은 2026년 11월 13일에 확인했습니다\.

## 준비할 것 {#section-8f0293675aafa119}

직접 만든 봇\, 봇을 실행할 서버\, Cryptanio 계정\, Payments 서비스가 활성화된 프로젝트를 준비하세요\. 해당 프로젝트의 Payments에 연결된 수신 주소와 인보이스 및 필요한 서비스에 대한 권한이 있는 유효한 API 키도 필요합니다\.

Telegram 봇 토큰\, Cryptanio API 키\, webhook 서명 검증용 시크릿은 서버에 보관하세요\. 구매자에게는 본인의 결제 링크만 전달합니다\. 이 시나리오는 상점을 자동으로 만들고 주문까지 처리해 주는 완성형 연동을 전제로 하지 않습니다\.

## 1\. 결제 프로젝트 준비하기 {#section-25540f9a6ecc5f57}

관리 화면에서 Payments를 활성화하고 서비스의 주소 풀에 수신 주소를 추가하세요\. 주소록에 주소를 저장하는 것만으로는 충분하지 않습니다\. 프로젝트에서 필요한 네트워크와 자산을 사용할 수 있는지 확인하세요\. 결제 페이지에 없는 선택지를 구매자에게 약속해서는 안 됩니다\.

USDT와 네트워크의 차이가 아직 명확하지 않다면 먼저 [「네트워크와 토큰」](<https://cryptanio.com/ko/wiki/network-wa-token/>)을 읽어 보세요\. [인보이스](<https://cryptanio.com/ko/wiki/invoice-ran/>)는 개별 결제 요청과 그 상태를 연결합니다\.

## 2\. 주문과 구매자 연결하기 {#section-ee5041791df8269d}

사용자가 포스터를 선택하고 주문을 확정하면 서버가 내부 주문 번호를 만듭니다\. 주문\, Telegram 구매자\, 앞으로 생성할 인보이스 ID의 연결 관계를 저장하세요\. 연락처와 배송 주소는 자체 시스템에 보관하세요\. 기술용 링크나 공개 메시지에 포함할 필요는 없습니다\.

저장한 인보이스 ID로 해당 주문을 하나로 특정할 수 있어야 합니다\. 그래야 봇을 다시 시작한 뒤에도 결제를 처리할 수 있습니다\.

## 3\. 별도 인보이스 만들기 {#section-5d3bb3edadddba74}

서버에서 API v1을 통해 인보이스 생성 작업을 호출하세요\. 구매자가 네트워크와 자산을 선택하는 시나리오라면 invoice\_currency와 invoice\_amount로 주문 견적을 지정합니다\. 예를 들어 USD 12\.50은 견적 단위를 뜻하며\, 실제 결제는 지원되는 암호화폐로 이루어집니다\. 달러를 받거나 자금을 자동으로 환전한다는 뜻은 아닙니다\.

아래는 문서 카탈로그에서 지원하는 주문 생성 예제를 참조하는 블록입니다\.

```bash
#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
: "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}"
json_string() {
  local text="$1" char code index output='"'
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in
      '"'|'\') output+="\\$char" ;;
      *) printf -v code '%d' "'$char"
         if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi
         output+="$char" ;;
    esac
  done
  printf '%s"' "$output"
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"invoice_currency":"USD","invoice_amount":"12.50","reference":"order-42"}' \
  "https://api.cryptanio.com/v1/invoices" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1
```

[예제 다운로드](</wiki/examples/ace23bd7c3cba0e47dafdcd6075a506ddb2ec8d6581c6129af815c1558f5a8fc.sh>)

자체 주문 매개변수를 전달하세요\. 새 작업에는 고유한 Idempotency\-Key가 필요하며\, 장애 후 동일한 요청을 다시 시도할 때는 기존 키를 유지해야 합니다\. 이렇게 해야 반복 클릭으로 청구서가 하나 더 생성되는 일을 방지할 수 있습니다\. 자세한 내용은 [주문 확인 가이드](<https://cryptanio.com/ko/wiki/webhook-jumun-gyeolje-hwagin/>)를 참고하세요\.

## 4\. 구매자에게 링크 보내기 {#section-6b7397b9cb54e285}

생성 응답의 checkout\_url을 저장하고 개인 채팅에서 링크 버튼으로 보내세요\. Bot API는 URL 버튼을 지원하며\, [InlineKeyboardButton](<https://core.telegram.org/bots/api#inlinekeyboardbutton>)에 설명되어 있습니다\. 구매자는 Cryptanio 페이지를 열고 이용 가능한 결제 방법을 선택합니다\.

받은 URL을 정확히 그대로 전달하세요\. ID로 링크를 조합하지 마세요\. 인보이스 조회 시 반환되는 링크는 열람용입니다\. 대화형 결제를 계속하려면 저장해 둔 생성 응답의 링크가 필요합니다\.

## 5\. 서버에서 결제 확인하기 {#section-6f3d5fbcf75d0461}

프로젝트의 [webhook](<https://cryptanio.com/ko/wiki/webhook-ran/>)이 자체 처리기를 가리키도록 설정하고 요청의 원본 본문으로 서명을 검증하세요\. 이벤트를 저장된 인보이스와 대조한 다음 API로 인보이스의 현재 상태를 확인합니다\.

성공 상태인 paid일 때만 주문 이행을 진행하세요\. 트랜잭션 감지\, 구매자의 채팅 복귀\, “결제했어요”라는 메시지는 이러한 확인을 대신하지 못합니다\. 부분 결제\, 부족 결제\, 초과 결제 또는 늦은 결제는 별도의 판단이 필요할 수 있으므로 이런 주문을 자동으로 확정하지 마세요\. webhook이 반복 전달되어도 주문을 중복 이행해서는 안 됩니다\.

## 확인 방법과 오류 점검 {#section-53bde8cfb337b5b8}

자체 주문으로 생성\, 링크 열기\, 결제\, 상태 변경\, 봇 메시지까지 전체 흐름을 확인하세요\. 네트워크 수수료를 고려하세요\. 이 방식으로 생성한 인보이스는 실제 데이터를 사용합니다\. 버튼 반복 클릭과 이벤트 재전달도 따로 점검하세요\.

자금은 보냈는데 주문이 확정되지 않았다면 네트워크\, 자산\, 결제 정보와 [트랜잭션 컨펌](<https://cryptanio.com/ko/wiki/transaction-hwagin/>)을 대조하세요\. 상태가 이미 paid라면 주문과 인보이스의 연결 관계 및 봇 처리기에서 오류를 찾으세요\. 소유자에게 보내는 Telegram 알림은 [별도 가이드](<https://cryptanio.com/ko/wiki/telegram-amhwahapye-georae-allim/>)에 따라 설정할 수 있지만\, 알림 자체가 서버의 주문 검증을 대신하지는 않습니다\.

태그: [결제](https://cryptanio.com/ko/wiki/tag/payments/), [Telegram](https://cryptanio.com/ko/wiki/tag/telegram/), [Webhooks](https://cryptanio.com/ko/wiki/tag/webhooks/)

## 관련 글

- [네트워크와 토큰의 차이](https://cryptanio.com/ko/wiki/network-wa-token/)
- [인보이스란 무엇인가](https://cryptanio.com/ko/wiki/invoice-ran/)
- [webhook으로 주문 결제를 자동 확인하는 방법](https://cryptanio.com/ko/wiki/webhook-jumun-gyeolje-hwagin/)