개발자 문서

스테이블코인 결제 주문 생성

서버에서 서명된 API 요청으로 USDT·USDC 주문을 생성하세요. 필수 항목, 네트워크, 전체 결제 금액, 결제 URL, 유효 시간과 Webhook 설정을 확인하고 주문 번호를 저장합니다.

POST /api/v1/order/create

인증 필요

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

USDTUSDC

정확한 금액 매칭

API가 반환하는 결제 금액이 조금 더 클 수 있는 이유는 무엇인가요?

출시 계획

고정 숫자 3개

비즈니스 프로

2-6개 구성 가능

설정된 식별 자릿수에 맞춰 금액을 올림합니다. 같은 네트워크, 통화, 수신 지갑에서 동일 금액을 쓰는 미결제 주문이 있으면 새 주문을 구별하기 위해 작은 차액을 더합니다. 청구 금액은 원래 금액보다 작아지지 않습니다. 무료 계정은 3자리로 고정되며 Pro 회원은 2–6자리를 선택할 수 있습니다. 응답의 payment.amount를 사용하세요.

매칭 흐름

주문 생성

1

amount

귀하의 백엔드가 결제 금액을 보내고 BoltUtil가 지불 가능한 온체인 금액을 반환합니다.

결제 표시

2

payment.amount

결제자에게 정확한 반품 금액, 네트워크, 수령 주소를 표시하세요.

온체인 결제 대조

3

Webhook

모니터는 네트워크, 주소, 토큰, 금액, 주문 상태 등을 매칭한 후 알려드립니다.

통합 참고사항

1

요청 금액이나 원래 제품 가격이 아닌 주문 생성 응답의 payment.amount를 표시합니다.

2

결제 지침을 표시할 때 작은 소수점 오프셋을 반올림하거나 자르거나 제거하지 마세요.

3

오프셋 정밀도 변경은 새로 생성된 주문에만 영향을 미치며 기존 보류 주문에는 영향을 미치지 않습니다.

4

externalOrderId로 처리하고 결제 상태를 확인하기 전에 Webhook 서명을 확인하고 알림을 중복 제거하세요. 결제 대기 중인 결제는 결제 성공이 아닙니다.

01. 요청 본문

JSON Payload
amount
필수
Decimal

currency에서 지정한 통화로 표시된 원래 제품 또는 비즈니스 주문 금액입니다. 부동 소수점 정밀도 손실을 방지하려면 문자열을 보냅니다. 지불인은 이 값이 아닌 반환된 payment.amount를 지불해야 합니다.

기본 최소 금액: 1.00. 선택한 네트워크와 통화에 설정된 최소 금액도 충족해야 합니다.정밀도 제한: 소수점 이하 6자리까지보안 위험: 프런트엔드에서 계산된 금액의 통과를 엄격히 금지합니다. 항상 백엔드 데이터베이스에서 값을 검색하세요.
externalOrderId
필수
String

귀하의 비즈니스 주문 ID는 BoltUtil 주문을 연결하는 데 사용됩니다. 쿼리는 externalOrderId를 사용합니다. 생성 응답은 merchantExternalId를 반환하고 Webhooks는 externalOrderId를 반환합니다.

판매자별로 전역적으로 고유해야 합니다지원: 문자, 숫자, 밑줄(_), 하이픈(-)길이 제한: 6 - 64자중복된 ID는 기존 주문이 아닌 오류를 반환합니다.
network
필수
String

아래 대문자 값 중 하나를 사용하여 결제 네트워크를 선택하세요. 예를 들어 Base에는 BASE를 사용하고 Ethereum에는 ERC20를 사용하세요.

예시 값

"network": "BASE"
허용되는 값: TRC20, ERC20, BEP20, POLYGON, SOLANA, BASE결제 시 동일한 네트워크를 표시합니다.
currency
필수
String

결제 통화를 선택하세요. USDT 또는 USDC만 전달합니다. network에서 별도로 네트워크를 지정하세요.

예시 값

"currency": "USDC"
허용되는 값: USDT, USDC⚠️ TRC20는 USDT만 지원합니다. 다른 쌍에는 활성화된 경로와 유효한 수신 지갑이 필요합니다.
orderDesc
String

주문 기록에 대한 선택적 제품 또는 비즈니스 요약입니다. 현재 결제에는 이 필드가 표시되지 않습니다.

권장 형식: 충전 - [사용자 계정]최대 길이: 255자
notifyUrl
URL

이 주문에 대한 Webhook 수신자입니다. 생략하면 판매자 대시보드에서 활성화된 기본 주소가 사용됩니다.

HTTPS여야 합니다공개적으로 접근 가능해야 합니다불변: 이 URL는 주문이 생성된 후에는 수정할 수 없습니다.주문을 생성하기 전에 대시보드에서 Webhook 및 서명 비밀을 구성하고 활성화하세요. 이 매개변수는 해당 구성을 대체하지 않습니다.최대 길이: 255자
returnUrl
URL

결제가 완료되거나 사용자가 반품을 선택한 후 결제 시 브라우저가 이 URL로 리디렉션됩니다. 탐색 목적지일 뿐이며 결제 성공을 증명하지는 않습니다.

서명된 Webhook 또는 주문 상태 쿼리를 통해 결제 확인생략할 경우 기본값은 https://boltutil.com입니다.최대 길이: 255자
expiredMinutes
Long

주문 생성 후 지불 가능 상태로 남아 있는 시간(분)입니다. 무료 플랜은 30분으로 고정되어 있습니다. Pro 회원은 15~60분을 선택할 수 있습니다.

구성 가능한 범위: 15~60분기본값: 30분Pro 회원만이 이 값을 맞춤 설정할 수 있습니다. 무료 플랜은 30분으로 고정되어 있습니다무료 계정은 유효한 범위 내의 맞춤 값을 무시하고 30분을 사용합니다. 실제 만료일로 time.expireTimestamp를 사용하세요.
metadata
Map

판매자가 정의한 JSON data. BoltUtil는 이를 수정하지 않고 주문 생성 응답, 주문 상태 응답 및 Webhook에서 변경되지 않은 상태로 반환합니다.

형식: 표준 JSON 개체변경되지 않은 상태로 반환되었으며 결제 매칭에 사용되지 않음최상위 키 최대 10개

02. 응답 세부정보

application/json
orderToken
결제 개시를 위한 BoltUtil 주문 식별자입니다. 판매자 API 쿼리는 externalOrderId를 사용합니다.
merchantExternalId
요청의 externalOrderId에 해당합니다.
status
성공적으로 생성된 후 PENDING입니다. 이후 결제 및 콜백 상태에 대해서는 주문 상태 문서를 참조하세요.
주문 상태 조회 →
checkoutUrl
독점 체크아웃 결제 링크
returnUrl
결제 반품 주소입니다. 생략되면 기본값은 https://boltutil.com입니다.
metadata
맞춤 패스스루 data 개체

data.payment { ... }

address
이 주문에 사용되는 판매자 수령 지갑입니다. 여러 주문이 이 주소를 공유할 수 있습니다. 주문당 새 주소가 생성되지 않습니다.
amount
정확한 지불 금액, 문자열로 반환됩니다. 반올림이나 잘림 없이 전체를 표시합니다.
rawAmount
가장 작은 토큰 단위의 금액으로, 정수 문자열로 반환됩니다: payment.amount × 10^payment.decimal. decimal = 6의 경우 1개의 토큰은 1,000,000개의 최소 단위와 같습니다.
currency
통화 기호.
network
네트워크 식별자.
qrData
결제 QR 코드를 생성하는 주소 문자열입니다. 금액, 통화, 네트워크는 포함하지 않습니다. payment.amount, currency, network를 별도로 표시하세요.
decimal
rawAmount를 환산하는 데 쓰는 해당 네트워크의 토큰 자릿수입니다. 주문 금액을 구별하는 자릿수와는 다릅니다.

data.time { ... }

expireTimestamp
data.time: 주문 만료 시간은 Unix 밀리초 timestamp입니다.
serverTimestamp
data.time: 응답이 생성된 서버 시간(Unix 밀리초 timestamp)

일반적인 오류

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

  • 401: API 키, 원시 본문 서명 및 현재 밀리초 timestamp(서버 시계 5분 이내)를 확인하세요.
  • 400: externalOrderId가 이미 존재합니다. 중복된 비즈니스 주문을 생성하는 대신 원래 주문을 쿼리하세요.
  • 400: 필수 매개변수, 사용 가능한 네트워크/자산, 지갑 수신 및 활성화된 Webhook 구성을 확인하세요.
  • 429: 요청 빈도 제한 또는 무료 일일 주문 생성 한도에 도달했습니다. 업무 오류 코드와 message를 확인하세요.
create / 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='{"amount":"25.00","currency":"USDT","network":"TRC20","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/create" \
  --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