Cryptanio
계정

웹사이트에서 USDC 결제를 받는 방법

미리 정한 네트워크에서 주문 한 건의 USDC 결제를 설정합니다. 정확한 토큰을 확인하고, 프로젝트에 주소를 연결한 뒤, 인보이스를 만들고 서버에서 결과를 확인하세요.

수정일:

웹사이트에서 USDC 결제를 받으려면 주문을 Cryptanio 인보이스와 연결하고 네트워크와 정확한 토큰을 미리 정해야 합니다. 여기서는 Ethereum의 USDC로 결제받기로 합의한 상점을 예로 들겠습니다. 서버가 주문별 인보이스를 만들면 구매자는 결제 페이지를 받게 되며, 결과를 확인한 후 주문을 확정합니다. 자금은 판매자의 주소로 입금됩니다.

이 시나리오에서는 자산이 고정되어 있습니다. 구매자는 이름이 비슷한 아무 코인이나 보내는 것이 아니라, 결제 정보에 지정된 USDC를 보내야 합니다. 결제 링크와 서버 연동 중 어느 방식을 선택할지는 웹사이트에서 암호화폐 결제를 받는 방법에서 설명합니다.

1. 어떤 USDC를 받을지 확인하기

네트워크와 토큰 식별자를 Circle 공식 목록과 대조하세요. USDC라는 이름과 지갑에 표시되는 로고만으로는 충분하지 않습니다. Circle이 해당 네트워크를 지원한다고 해서 Cryptanio 프로젝트에서도 그 경로가 활성화되어 있다는 뜻은 아닙니다.

Circle은 발행사가 해당 네트워크에서 직접 발행하는 native USDC와 제삼자 브리지가 만든 bridged USDC를 구분합니다. 인보이스 결제에서 이 둘을 서로 대체할 수 있다고 보아서는 안 됩니다. 차이는 Circle의 설명에서 확인할 수 있습니다. 여기서는 Ethereum에서 지원되는 Circle USDC를 선택합니다. 다른 네트워크를 사용하려면 해당 토큰과 사용 가능 여부를 다시 확인하세요.

native USDC의 native는 블록체인의 기본 코인을 뜻하지 않습니다. Ethereum에서 USDC는 여전히 토큰이며, 기본 코인은 ETH입니다. 주소를 입력할 때 이 차이를 알아야 합니다.

2. 해당 자산을 받을 주소 준비하기

«결제» 서비스가 활성화된 프로젝트, 본인 지갑의 공개 주소, 프로젝트 설정 권한이 필요합니다. «결제»를 열고 프로젝트와 «주소» 섹션을 선택한 다음 «주소 추가»를 누르세요. «수동으로» 탭에서 Ethereum을 선택하고 직접 관리하는 주소를 입력합니다.

«자산 1개»를 선택한 뒤 «자산»에 해당 네트워크에서 지원되는 USDC의 식별자를 입력하세요. 이 식별자는 Circle 목록과 대조해야 합니다. 필드를 비워 두면 native USDC가 아니라 기본 코인을 의미합니다. «수신»을 켜 둔 상태로 주소를 추가하고, 연결이 활성화되어 있는지와 네트워크를 사용할 수 있는지 확인하세요. 주소록에 저장하는 것만으로는 필요한 서비스의 입금 수신에 연결되지 않습니다.

수동 주소 풀에는 결제 정보로 배정할 수 있는 미사용 주소를 준비하세요. 개인 키나 시드 문구는 제공하지 마세요. 공개 주소를 연결하는 데 필요하지 않습니다. 네트워크와 토큰의 조합을 확인하는 기본 사항은 «네트워크와 토큰은 어떻게 다른가요?»에서 설명합니다.

3. 주문용 인보이스 만들기

서버에서 사용할 운영용 API 키를 준비하세요. 이 프로젝트에 접근할 수 있고 invoices(«인보이스») 섹션에 «읽기 및 쓰기» 권한이 있어야 합니다. 요청을 보내기 전에 자체 주문 번호를 저장하세요. 키를 구매자에게 전달해서는 안 됩니다.

아래는 자산을 고정하는 API v1의 지원 예제입니다. 생성된 요청에서 주문에 사용할 네트워크, 자산, 금액을 확인하세요. USDC 금액은 토큰 수량을 뜻하며, 은행 계좌로 달러를 받는다는 의미가 아닙니다.

#!/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")"',"chain":"ethereum","asset":"USDC","amount":"12.50","reference":"order-42","expires_in":60,"customer":{"id":"customer-42"},"metadata":{"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

예제 다운로드

자신의 프로젝트와 주문 정보를 지정하세요. 새 작업에는 고유한 Idempotency-Key를 사용하고, 오류 발생 후 동일한 요청을 다시 보낼 때는 이전 키를 유지하세요. 주문과 생성된 인보이스 ID의 연결 관계, 응답으로 받은 checkout_url, 정확한 결제 정보를 저장하세요. 응답의 금액을 반올림하거나 가격표에 있는 숫자로 바꾸지 마세요.

4. 고객에게 결제 페이지 전달하기

웹사이트의 주문 화면에서 응답으로 받은 checkout_url을 열 수 있게 하세요. 인보이스 ID로 페이지 주소를 직접 조합하거나 배정된 결제 정보 대신 고정 지갑 주소를 넣지 마세요. 이 시나리오에서는 네트워크와 자산이 이미 선택되어 있으므로, 고객은 전송하기 전에 지갑에서 두 항목을 확인해야 합니다.

지갑의 수수료 규칙과 결제 기한을 고려해 정확한 금액을 보내도록 안내하세요. 고객이 다른 버전의 USDC를 가지고 있다면 토큰 이름만 바꾼다고 해당 전송이 유효한 결제가 되지는 않습니다. 먼저 올바른 전송 경로에 합의하세요. Cryptanio가 자동 환전이나 브리지를 제공한다고 약속해서는 안 됩니다.

5. 주문을 확정하고 전체 과정 확인하기

서버는 webhook이나 API 폴링을 통해 인보이스의 최신 상태를 확인해야 합니다. 상태가 paid일 때 주문을 이행하고, 중복 이행을 방지하는 보호 장치를 유지하세요. 트랜잭션이 발견되었다는 사실, 스크린샷, 구매자가 사이트로 돌아왔다는 사실은 이 확인을 대신하지 못합니다.

부족 입금, 초과 입금, 기한이 지난 입금, 트랜잭션의 되돌림은 해당 인보이스의 상태에 따라 처리하세요. 판단이 어려우면 TXID를 저장하고 미결제 주문 진단 안내를 활용하세요. 금액이 비슷하다는 이유만으로 다른 자산의 입금을 이 주문에 배정하지 마세요.

직접 만든 주문으로 결제 정보, 전송, 확인, 주문 이행까지 전체 과정을 점검하세요. 운영 모드에서는 실제 자금과 네트워크 수수료가 사용됩니다. 페이지의 외관이나 인위적인 이벤트만 확인해서는 선택한 USDC가 실제로 입금되고 올바르게 집계된다는 사실을 입증할 수 없습니다.

관련 글