
API 호출 한 번으로 웹사이트에서 USDT 결제 받기
Suawave로 USDT 결제를 받는 방법을 알아보세요. 입금 주소 생성, 네트워크와 QR 코드 표시, 콜백 검증, 정산 후 주문 업데이트까지 설명합니다.
게시일 , 수정일
Suawave로 USDT 결제를 받으려면 정산 주소와 HTTPS 콜백 URL로 입금 주소를 생성하세요. 구매자에게 주소, 네트워크, 최소 입금액을 안내합니다. 각 콜백의 서명을 검증하고 이벤트를 주문과 대조한 뒤, 확정 콜백에서 충분한 USDT 수령을 확인했을 때만 주문을 이행하세요.
제목의 API 호출 한 번은 입금 주소를 생성하는 호출입니다. 웹사이트에는 별도로 결제 화면과 콜백 핸들러가 필요합니다. 전체 흐름은 Suawave 빠른 시작에서 확인할 수 있습니다.
1. 네트워크를 선택하고 최소 입금액 확인하기
네트워크와 자산을 함께 식별하는 티커를 사용하세요. 이 글의 예제는 TRON의 USDT를 뜻하는 trc20/usdt를 사용합니다. 결제 과정 내내 네트워크를 표시하세요. “USDT”만 표시하면 구매자가 전송할 때 필요한 정보가 빠집니다.
주문을 생성하기 전에 GET /trc20/usdt/info/를 요청하세요.
curl "https://api.suawave.com/trc20/usdt/info/"
응답에서 minimum_transaction_coin을 확인하세요. 금액은 십진수 문자열로 다루고, 애플리케이션에서는 정확한 십진수 연산이나 자산의 최소 단위를 사용하는 정수 연산을 적용하세요.
최소 금액과 수수료는 다음 출처를 기준으로 처리하세요.
| 결제 화면 정보 | 출처 |
|---|---|
| 선택한 티커의 최소 입금액 | info 또는 create의 minimum_transaction_coin |
| 생성된 주소의 수수료 필드 | create 응답 |
| 입금 한 건에서 실제 정산된 금액 | 해당 확정 콜백의 value_forwarded_coin |
차감 방식은 수수료와 최소 금액 가이드를 참고하세요. 정산 비용 추산 엔드포인트의 응답을 USDT 입금에서 차감될 수수료 견적으로 사용하지 마세요. 이 엔드포인트는 네트워크의 네이티브 코인으로 설정된 상한값을 반환합니다.
2. 입금 주소 생성하기
서버에 주문 참조값과 새로 생성한 추측 불가능한 nonce를 저장하세요. 나중에 핸들러에서 저장된 주문과 대조할 수 있도록 두 값을 콜백 URL에 넣으세요.
정산 주소와 해당 콜백 URL로 GET /trc20/usdt/create/를 호출하세요. 아래 요청은 빠른 시작의 예제입니다. 사용하기 전에 예시 주소, 주문 참조값, nonce를 실제 값으로 교체하세요.
curl -G "https://api.suawave.com/trc20/usdt/create/" \
--data-urlencode "address=TXyzPayoutAddressExample0000000000000" \
--data-urlencode "callback=https://shop.example/hook?order=1001&nonce=7f3a9c" \
--data-urlencode "pending=1"
위의 짧은 nonce는 자리표시자일 뿐, nonce 생성 방법의 예시는 아닙니다. 사용하는 플랫폼의 암호학적 난수 생성기로 생성하세요.
반환된 address_in을 주문에 저장하세요. 이 주소는 구매자의 입금 목적지입니다. address_out은 판매자의 정산 목적지이므로 둘을 혼동하면 결제 흐름이 잘못됩니다.
정규화된 티커와 콜백 쌍으로 주문을 식별합니다. 같은 쌍으로 반복 호출하면 기존 입금 주소를 반환하며, 콜백 옵션은 첫 호출에서 고정됩니다. 같은 쌍에 다른 정산 주소를 지정하면 거부합니다. 개별 추적할 주문마다 서로 다른 콜백 URL을 사용하세요.
콜백 URL 정규화 방식과 전체 create 파라미터는 API 레퍼런스에 설명되어 있습니다. 콜백 엔드포인트에는 HTTPS를 사용하고 각 쿼리 값을 URL 인코딩하세요. 사설 네트워크나 루프백을 가리키는 콜백 목적지는 거부합니다.
3. 입금 주소와 QR 코드 표시하기
구매자에게 반환된 입금 주소, 선택한 자산과 네트워크, 주문 금액, 최소 입금액을 표시하세요. QR 코드를 표시하더라도 금액은 텍스트로 함께 보여 주세요.
create에서 받은 실제 address_in으로 GET /trc20/usdt/qrcode/를 요청하세요. 아래 문서 예제 역시 자리표시자 주소와 예시 금액을 사용합니다.
curl -G "https://api.suawave.com/trc20/usdt/qrcode/" \
--data-urlencode "address=TDepositAddressExample0000000000" \
--data-urlencode "value=25.5"
응답에는 이미지 소스로 사용할 PNG data URI인 qr_code와 QR에 인코딩된 정확한 텍스트인 payment_uri가 있습니다.
TRON에서 인코딩되는 텍스트는 입금 주소뿐입니다. API는 value를 검증하지만 QR 페이로드에는 넣지 않습니다. 구매자가 지갑에서 금액을 직접 입력해야 합니다. EVM 토큰에서는 value를 넣은 요청이 EIP-681 토큰 전송 요청을 인코딩합니다. 지갑별 지원 여부가 다르고 결제자가 금액을 변경할 수도 있습니다.
QR 스캔만으로 결제 금액이 확정되지는 않습니다. 콜백 핸들러에서 검증된 결제 데이터를 기준으로 판단해야 합니다.
4. 주문을 변경하기 전에 모든 콜백 검증하기
콜백은 기본적으로 GET 요청으로 도착합니다. create에서 post=1을 설정하면 form POST, json=1을 설정하면 JSON POST를 사용합니다. 둘 다 있으면 json=1이 우선합니다. 직접 지정한 콜백 쿼리 파라미터는 URL에 유지됩니다.
x-ca-signature 헤더를 읽고 GET /pubkey/에서 받은 공개 키로 검증하세요. GET 검증에는 원래 쿼리 순서를 포함한 정확한 전체 URL을 사용합니다. POST 검증에는 파싱 전 원본 요청 본문을 사용합니다. 사용하는 언어의 서명 검증 예제를 참고하세요.
서명을 검증한 뒤 주문 참조값과 nonce를 저장된 값과 대조하세요. address_in과 coin도 확인하세요. 티커가 trc20/usdt이면 콜백의 coin 값은 trc20_usdt입니다.
pending=1을 사용하면 처리 조건을 충족한 입금에 대해 다음 이벤트를 받을 수 있습니다.
| 콜백 필드 | 의미 | 결제 화면 처리 |
|---|---|---|
pending이 "1" |
입금 감지 | 대기 상태를 표시하고 주문은 이행하지 않음 |
pending이 "0" |
정산 트랜잭션 확정 | 확정 금액이 주문 조건을 충족하는지 판단 |
pending 이벤트와 확정 이벤트는 서로 다른 UUID를 사용합니다. 같은 이벤트의 재시도는 같은 UUID를 유지합니다. 재시도로 주문을 두 번 이행하지 않도록 처리한 UUID를 영구 저장하세요.
5. 결제를 기록하고 수신 확인하기
확정 콜백에는 입금액인 value_coin, 부과된 수수료인 fee_coin, 정산 주소에 도착한 금액인 value_forwarded_coin이 포함됩니다. 주문 정책에 어떤 금액을 사용할지 정하고 정확한 연산으로 비교하세요.
수신 확인 전에 이벤트와 그에 따른 주문 변경을 함께 영구 저장하세요. 30초 안에 HTTP 200과 일반 텍스트 본문 *ok*를 반환하세요. 이미 처리한 이벤트라면 작업을 반복하지 않고 같은 수신 확인을 반환합니다.
재시도로 콜백 도착 순서가 바뀔 수 있습니다. 늦게 도착한 pending 이벤트가 확정된 입금을 대기 상태로 되돌려서는 안 됩니다. 수신 확인 규칙, 재시도, 이벤트 순서는 콜백 가이드를 참고하세요.
콜백이 누락되면 최초 콜백 URL로 GET /trc20/usdt/logs/를 호출해 정산 및 전달 내역을 조회할 수 있습니다. 이를 대조를 위한 보완 수단으로 사용하세요. sent 결과는 정산은 확정되었지만 확정 콜백의 수신 확인은 아직 받지 못했다는 뜻이며, 재시도가 모두 소진된 경우도 포함합니다.
금액이 부족하거나 여러 번 결제하면 어떻게 되나요?
USDT 최소 입금액은 얼마인가요?
고정 금액을 결제 화면에 복사해 넣지 말고 선택한 티커의 minimum_transaction_coin을 읽으세요. 입금에 적용되는 최소 금액은 해당 입금이 처음 감지된 시점의 값입니다.
구매자가 주문 합계보다 적게 보내면 어떻게 하나요?
주문 합계와 티커의 최소 금액을 구분하세요. 처리 가능한 입금이어도 주문 합계보다 적을 수 있습니다. 검증된 확정 입금이 금액 정책을 충족할 때까지 주문을 미결제 상태로 유지하세요. 처리 가능한 입금은 각각 별도로 정산되고 고유한 확정 콜백이 발생하므로, 금액을 합산하기 전에 이벤트 중복을 제거하세요.
티커의 최소 금액 미만인 입금은 정산되지 않고 콜백도 발생하지 않으며 공개 로그에도 나타나지 않습니다. 구매자가 보내기 전에 결제 화면에서 최소 금액을 분명히 안내해야 합니다.
결제는 언제 확정되나요?
이 연동에서는 서명과 주문 정보를 검증한 뒤 pending이 "0"인 이벤트에 따라 주문을 이행합니다. 이 이벤트는 정산 트랜잭션 확정 후 발생합니다. 입금 감지, QR 스캔, create의 API 응답만으로는 주문이 결제되었다고 판단할 수 없습니다.