개발자 문서

결제 결과 및 주문 상태 조회

판매자 주문 ID로 조회하며 결제 확인, 알림 전달, 상품 제공을 구분하세요.

POST /api/v1/order/status

인증 요청

X-Bolt-Key, X-Bolt-Timestamp 및 X-Bolt-Signature를 포함합니다. 현재 밀리초 timestamp를 사용하고 정확한 요청 본문과 함께 timestamp에 서명하세요.

01. 요청 매개변수

application/json
externalOrderId필수
String

orderToken가 아닌 주문 생성 시 사용한 판매자 externalOrderId를 보내세요. 현재 API 키에 속한 주문만 조회할 수 있습니다.

예시 값

{"externalOrderId": "INV-20260209-99281"}

필수 문자열, 6~64자. 문자, 숫자, 밑줄(_), 하이픈(-)이 허용됩니다.

Body

주문 상태 및 처리

PENDING

결제 대기 중: 적합한 송금이 일치하지 않습니다.

PAID

결제가 감지되었으며 블록체인 확인을 기다리고 있습니다.

CONFIRMED

판매자 검토를 통해 결제가 확인되거나 승인되었습니다. 콜백 전달이 아직 보류 중일 수 있습니다.

COMPLETED

결제가 확인되었으며 BoltUtil가 성공적인 콜백 응답을 받았습니다.

EXPIRED

적격한 이체가 일치하지 않고 결제 기간이 종료되었습니다. 확인이 지연된 정시 환승은 나중에 인정될 수도 있습니다.

FAILED

주문이 실패한 상태입니다. 결제 성공으로 처리하지 마세요.

CANCELLED

주문이 취소되었습니다. 결제 성공으로 처리하지 마세요.

PAID는 확인 대기 상태이므로 이 상태만으로 상품을 제공하지 마세요. CONFIRMED 또는 COMPLETED는 결제가 확인되었음을 뜻합니다. externalOrderId마다 한 번만 제공하세요. COMPLETED는 BoltUtil이 알림에 대한 성공 응답을 받았다는 뜻이며, 가맹점의 제공 완료를 증명하지 않습니다. 수동 검토한 결제는 실제 지불 금액과 정산 유형도 확인하세요.

02. 응답 필드(data)

application/json
statusString
현재 주문 상태. 위의 상태 설명을 참조하세요. 주문이 모든 주를 통과할 필요는 없습니다.
amountString
지급 가능한 주문 금액으로, 문자열로 반환됩니다. 기록된 지불 금액에 paidAmount를 사용하세요.
paidAmountString / null
지급 금액을 문자열로 기록합니다. 결제 전 null일 수 있습니다. 별도의 결제 금액이 없는 이전 유료 주문의 경우 결제 금액으로 대체됩니다.
shortfallAmountString / null
부족액을 문자열로 기록합니다. 결제 전 null일 수 있습니다. 수동으로 허용된 초과 지불은 여기에서 0을 반환할 수 있습니다. 부호 있는 차이를 계산하려면 amount에서 paidAmount를 빼세요.
settlementTypeString / null
EXACT: 정확히 일치; MANUAL_UNDERPAID: 미지불이 허용됨; MANUAL_OVERPAID: 초과 지불이 허용되었습니다. MANUAL_AMBIGUOUS: 수동으로 검토된 또 다른 연결입니다. 결제 전 null일 수 있습니다.
paymentRouteString / null
실제 결제 경로: DIRECT는 직접 송금, SPLIT은 분할 지급입니다. 정산 전 조회 시 null일 수 있으며 결제 확인을 의미하지 않습니다.
platformFeeString / null
currency와 같은 통화의 실제 플랫폼 수수료(문자열)입니다. 기록 전 조회 시 null일 수 있습니다. 직접 송금·면제 결제는 0이며 네트워크 비용은 제외됩니다.
merchantNetAmountString / null
currency와 같은 통화의 판매자 순수령액(문자열)입니다. 분할 지급 시 총 결제액에서 플랫폼 수수료를 뺍니다. 기록 전 조회에서는 null, 과거 콜백에서는 실결제액을 사용할 수 있습니다.
manuallyAcceptedBoolean
현재 true는 MANUAL_UNDERPAID에만 해당됩니다. 모든 직접 조치를 식별하지는 않습니다. 특정 유형에는 settlementType를 사용하세요.
externalOrderIdString
생성 시 제공되는 판매자 주문 ID는 비즈니스 주문을 쿼리하고 연결하는 데 사용됩니다.
txHashString / null
관련 결제의 거래 해시입니다. 연결 전 null일 수 있습니다. 해시만으로는 결제 확인을 증명할 수 없습니다.
destinationAddressString
이 주문에 사용되는 판매자 수신 지갑입니다. 여러 주문이 공유될 수 있습니다.
confirmationsInteger / null
기록된 블록체인 확인 횟수; null일 수 있습니다. 확인 규칙은 네트워크에 따라 다릅니다. status를 사용하여 결제 확인을 결정하세요.
currencyString
USDT 또는 USDC와 같은 결제 통화 코드입니다.
networkString
결제 네트워크 코드: TRC20, ERC20, BEP20, POLYGON, SOLANA 또는 BASE.
paidAtString / null
날짜-시간 문자열로 결제 시간을 기록합니다. null 결제가 기록되기 전
confirmedAtString / null
결제 확인 시간을 날짜-시간 문자열로 기록합니다. 확인 전 null.
completedAtString / null
주문이 처음 입력된 시간 COMPLETED를 날짜-시간 문자열로 입력합니다. 완료 전 null. 성공적인 반복 전달은 이를 덮어쓰지 않습니다. 이전에 완료된 주문은 기록된 시간을 그대로 유지합니다.
metadataObject
주문 생성 시 제공되는 맞춤 JSON 개체입니다. 결제 매칭에는 사용되지 않습니다.

쿼리 메모

  • 쿼리는 저장된 주문 상태를 반환합니다. 블록체인을 즉시 스캔하지 않습니다. 확인은 기록된 값입니다. 결제 확인을 결정하려면 status를 사용하세요.
  • 일치하는 결제가 없으면 paidAmount, shortfallAmount, settlementType, txHash 및 관련 시간은 null가 될 수 있습니다. 이는 쿼리 실패가 아닙니다.
  • 본인의 주문만 조회할 수 있습니다. 무료 계정은 지난 30일 이내에 생성된 주문에 액세스할 수 있습니다. 활성 회원은 모든 기록에 접근할 수 있습니다. 누락되었거나 액세스할 수 없는 주문, 반품 주문을 찾을 수 없습니다.
  • paidAt, confirmedAt 및 completedAt는 시간대 오프셋이 없는 2026-02-09T18:20:50.790과 같은 날짜-시간 문자열입니다. 밀리초 타임스탬프가 아닙니다.

일반적인 오류

이러한 경우는 일반적인 경우입니다. 실제 HTTP 상태와 응답 코드/메시지를 사용하여 실패를 진단합니다. 오류 응답은 결제 결과가 아닙니다.

  • 401: API 키, 원시 본문 서명 및 현재 밀리초 timestamp(서버 시계 5분 이내)를 확인하세요.
  • 404: 주문이 누락되었거나, 다른 판매자에게 속해 있거나, 요금제에서 허용하는 내역을 벗어났습니다.
status / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/status" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

주소, 거래 해시 및 주문은 예시입니다. 이를 자신만의 테스트 data로 바꾸세요.

Base URL

PROD
https://api.boltutil.com