개발 문서

자주 묻는 질문

입금 주소 생성부터 확정 콜백 처리까지, Suawave로 암호화폐 결제를 받는 방법을 알아보세요.

시작하기

계정 없이 USDT TRC20 결제를 받으려면 어떻게 하나요?

Suawave는 가입이나 계정, API 키 없이 USDT TRC20 결제를 받을 수 있습니다. 정산 주소와 외부에서 접근 가능한 HTTPS 콜백 URL을 넣어 GET /trc20/usdt/create/를 호출하세요. 반환된 address_in과 minimum_transaction_coin을 선택한 티커의 자산 및 네트워크 정보와 함께 결제자에게 안내하면 됩니다.

개발 문서 보기
주문마다 다른 입금 주소를 생성하려면 어떻게 하나요?

각 Suawave 주문에 주문 참조값과 추측할 수 없는 nonce를 포함한 고유 콜백 URL을 사용하세요. 같은 티커와 콜백으로 create를 반복하면 같은 입금 주소를 반환하고 최초 옵션을 유지합니다. 정확한 콜백 URL을 서버에 보관하세요.

개발 문서 보기

코인과 네트워크

Suawave는 어떤 코인과 네트워크를 지원하나요?

Suawave에서 활성화된 결제 경로는 BNB Smart Chain BEP20의 USDC (bep20/usdc); BNB Smart Chain BEP20의 USDT (bep20/usdt); TRON TRC20의 USDT (trc20/usdt)입니다. 선택한 토큰과 네트워크에 해당하는 소문자 티커를 정확히 사용하세요. 지갑 주소만으로는 토큰 표준을 구분할 수 없습니다.

개발 문서 보기
고객이 다른 토큰이나 잘못된 네트워크로 보내면 어떻게 되나요?

Suawave는 주문에 지정된 토큰과 네트워크만 처리합니다. 다른 토큰의 전송은 정산되지 않으며 공개 콜백이나 로그 항목도 생성되지 않습니다. 다른 네트워크로 보낸 금액을 복구하거나 결제로 인정할 수 있다고 가정하지 마세요.

개발 문서 보기

수수료와 최소 금액

Suawave의 건별 결제 수수료는 얼마인가요?

Suawave는 각 입금에 최소 금액이 적용되는 서비스 수수료와 네트워크 수수료를 결제 토큰으로 부과합니다. 지난 30일 USD 결제 금액에 따른 서비스 수수료 구간은 $250,000 미만: 0.50%; $250,000 ~ $999,999: 0.45%; $1,000,000 ~ $2,499,999: 0.40%; $2,500,000 ~ $4,999,999: 0.35%; $5,000,000 ~ $9,999,999: 0.30%; $10,000,000 ~ $19,999,999: 0.20%; $20,000,000 이상: 0.13%입니다. 공개된 토큰별 수수료는 BNB Smart Chain BEP20 USDC: 최소 서비스 수수료 0.05 USDC, 네트워크 수수료 0.05 USDC; BNB Smart Chain BEP20 USDT: 최소 서비스 수수료 0.05 USDT, 네트워크 수수료 0.05 USDT; TRON TRC20 USDT: 최소 서비스 수수료 0.05 USDT, 네트워크 수수료 1.00 USDT입니다. 수수료는 입금별로 결정하며, fee_coin과 value_forwarded_coin에 실제 수수료와 정산액이 표시됩니다.

개발 문서 보기
Suawave에서 받을 수 있는 최소 암호화폐 결제 금액은 얼마인가요?

Suawave는 토큰과 네트워크별로 최소 입금액을 적용합니다: BNB Smart Chain BEP20 USDC: 1.00 USDC; BNB Smart Chain BEP20 USDT: 1.00 USDT; TRON TRC20 USDT: 10.00 USDT. 결제 안내를 표시하기 전에 create 또는 info의 minimum_transaction_coin을 확인하세요. 각 입금에 적용되는 최소 금액은 해당 입금이 처음 감지될 때 저장됩니다.

개발 문서 보기
최소 금액 미만의 입금을 여러 번 보내면 합산해서 결제로 인정되나요?

아니요. Suawave는 각 입금에 최소 금액 기준을 개별 적용하므로, 최소 금액 미만의 입금을 여러 번 보내도 처리 가능한 입금으로 합산되지 않습니다. 최소 금액 미만의 입금은 전송이나 정산이 이루어지지 않고, 콜백도 보내지 않으며 공개 로그에도 나타나지 않습니다.

개발 문서 보기

컨펌과 결제 확정

Suawave 결제를 언제 결제 완료로 처리할 수 있나요?

pending이 0인 Suawave 확정 콜백의 서명을 검증하고 주문, 토큰, 주소, 금액을 확인한 뒤에만 주문을 결제 완료로 처리하세요. 이 이벤트는 처리 대상 입금이 전송되고 정산 트랜잭션까지 확정되었음을 뜻합니다. pending 콜백만으로는 주문을 이행하면 안 됩니다.

개발 문서 보기
Suawave에 필요한 컨펌 수는 몇 회이며, 변경할 수 있나요?

Suawave는 호출자가 정한 컨펌 수 대신 선택한 체인의 최종성 정책을 따릅니다. TRON은 solidified 상태를 확인하고 BNB Smart Chain은 finalized 헤더를 사용합니다. 공개 create 엔드포인트에서는 컨펌 수나 우선순위를 직접 지정할 수 없습니다. 인덱싱과 정산 전송에도 시간이 걸리므로 블록 생성 간격이 결제 완료 시간을 의미하지는 않습니다.

개발 문서 보기
pending 웹훅을 받으면 고객이 결제를 완료한 건가요?

pending이 1인 Suawave 콜백은 인덱서가 처리 대상 입금을 감지했다는 뜻이며, 정산 전송이 확정되었다는 뜻은 아닙니다. 이 선택적 이벤트를 받으려면 최초 create 호출에 pending=1을 넣으세요. pending 이벤트와 확정 이벤트는 서로 다른 UUID를 사용하며 순서가 뒤바뀌어 도착할 수 있습니다.

개발 문서 보기

콜백과 서명 검증

Suawave 웹훅을 JSON이나 form POST로 받을 수 있나요?

네. Suawave는 기본적으로 GET 콜백을 보내며, post=1이면 form POST, json=1이면 JSON POST를 보냅니다. 둘 다 설정하면 JSON이 우선합니다. 티커와 콜백 쌍의 옵션은 최초 create 호출에서 고정되며, 사용자 지정 쿼리 파라미터는 콜백 URL에 유지됩니다.

개발 문서 보기
Suawave 웹훅 서명을 어떻게 검증하나요?

GET /pubkey/에서 받은 Suawave 공개 키로 x-ca-signature 헤더의 base64 RSA-SHA256 PKCS#1 v1.5 서명을 검증하세요. GET 콜백은 원본 요청 URL 전체에, POST 콜백은 원본 본문의 정확한 바이트에 서명합니다. 필드를 파싱하거나 신뢰하기 전에 검증하세요. 키는 캐시하고, 검증에 실패하면 한 번 갱신한 뒤 다시 검증하고, 그래도 검증에 실패하는 경우에만 요청을 거부하세요.

개발 문서 보기
웹훅 수신은 어떻게 확인하나요? Suawave가 재시도하나요?

Suawave 콜백을 수신 확인하려면 30초 안에 HTTP 200과 *ok*를 반환하세요. 별표 없는 ok도 대소문자 구분 없이 허용됩니다. 총 8회 시도하며, 최초 전송 후 30초, 2분, 10분, 30분, 2시간, 6시간, 24시간의 지연 간격에 최대 10%의 지터를 더해 재시도합니다. 재시도에는 같은 uuid를 사용하므로 중복 처리를 막도록 영구 저장하세요.

개발 문서 보기
웹훅이 도착하지 않으면 결제를 어떻게 확인하나요?

최초 콜백 URL로 Suawave의 GET /trc20/usdt/logs/를 호출하여 처리 대상 입금과 내부 기록을 대조하세요. 결과의 pending은 정산 미확정, sent는 정산이 확정되었지만 확정 콜백의 수신 확인은 아직 없음, done은 해당 콜백의 수신 확인까지 완료됨을 뜻합니다. 최소 금액 미만, 미지원, 지연 전송은 로그에 없을 수 있으므로 빈 로그가 전송 자체가 없었다는 증거는 아닙니다.

개발 문서 보기

부족 입금, 초과 입금, 지연 입금

고객이 주문 금액보다 적게 보내면 어떻게 하나요?

확정된 금액이 주문 금액을 충족하는지는 쇼핑몰에서 판단합니다. Suawave의 공개 create 엔드포인트에는 청구 금액을 전달하지 않습니다. 총입금액 기준이면 value_coin을, 순수령액 기준이면 value_forwarded_coin을 사용해 처리 대상 확정 입금을 합산하고 콜백 UUID로 중복을 제거하세요. 추가 입금도 각각 최소 입금액을 충족해야 하며 수수료가 별도로 부과됩니다.

개발 문서 보기
고객이 암호화폐를 너무 많이 보내면 어떻게 되나요?

Suawave는 쇼핑몰 주문 금액을 초과한 부분을 포함하여 처리 대상 입금에서 수수료를 뺀 금액을 전송합니다. 공개 API는 초과 금액을 자동 환불하지 않습니다. 쇼핑몰에서 처리 방침을 정하고 필요한 환불은 자체 지갑에서 진행해야 합니다.

개발 문서 보기
입금 주소가 만료된 뒤에 고객이 결제하면 어떻게 되나요?

주문에서 허용하는 만료 범위를 벗어난 Suawave 입금은 검토를 위해 보류되며, 정산되지 않고 공개 콜백이나 로그 항목도 생성되지 않습니다. 처리 가능 여부는 전송의 유효 시각과 저장된 만료 시각에 설정된 유예 시간을 더한 값을 기준으로 판단하므로, 기한 내 전송이 나중에 확정될 수는 있습니다. 만료된 주소는 표시를 중단하고 지연 입금은 수동으로 대조하세요. 결제자에게 자동으로 환불된다고 보장하지 않습니다.

개발 문서 보기

정산과 전송

Suawave는 결제 금액을 판매자 지갑으로 어떻게 보내나요?

Suawave는 수수료와 체인 검증을 거친 뒤 처리 가능한 각 입금을 create에 지정한 단일 정산 주소로 개별 전송합니다. 확정 콜백에는 txid_out과 value_forwarded_coin이 포함되므로 서버에서 정산 트랜잭션과 순수령액을 확인할 수 있습니다.

개발 문서 보기
정산 주소를 변경하거나 여러 지갑으로 나눠 받을 수 있나요?

Suawave는 티커와 콜백 쌍마다 하나의 정산 주소를 연결하며, 기존 쌍의 주소는 변경할 수 없습니다. 다른 정산 주소를 사용하려면 새 콜백 URL로 새 주문을 만드세요. 공개 API는 비율 분할이나 여러 정산 목적지를 지원하지 않습니다.

개발 문서 보기

보안과 자금 보관

Suawave가 정산 전에 암호화폐를 보관하나요?

Suawave는 게이트웨이가 제어하는 입금 주소로 결제를 받은 뒤 처리 가능한 자금을 판매자의 정산 지갑으로 전송합니다. 전송은 즉시 또는 무조건 이루어지지 않습니다. 체인 검증, 수수료, 최소 금액, 만료 규칙을 적용하며 처리 대상이 아닌 입금은 보류될 수 있습니다.

개발 문서 보기
전체 콜백 URL을 비밀로 유지해야 하는 이유는 무엇인가요?

전체 Suawave 콜백 URL로 해당 주문의 공개 API 로그에 접근할 수 있으므로, 추측할 수 없는 nonce를 포함해 서버에만 보관하세요. 수신 콜백은 여전히 서명 검증이 필요합니다. 유효한 서명도 저장된 주문, 예상 토큰, 주소, 금액과 대조해야 합니다.

개발 문서 보기

플러그인, SDK, MCP

WooCommerce, Magento, OpenCart, PrestaShop에서 암호화폐 결제를 받을 수 있나요?

Suawave는 WooCommerce, Magento 2, OpenCart, PrestaShop용 쇼핑몰 연동을 제공합니다. 각 연동 가이드에 따라 플러그인을 설치하고 설정하여 입금 주소와 QR 코드를 표시하고 서명된 결제 콜백을 처리하세요.

개발 문서 보기
Suawave 연동에는 어떤 SDK를 사용할 수 있나요?

Suawave는 공개 API용 Go 및 JavaScript/TypeScript SDK를 제공합니다. HTTP 엔드포인트를 직접 호출할 수도 있으며, 콜백 핸들러에는 Go, JavaScript, PHP, C# 서명 검증 예제를 활용할 수 있습니다.

개발 문서 보기
AI 어시스턴트가 MCP로 Suawave를 사용할 수 있나요?

네. Suawave MCP 서버는 입금 주소 생성과 결제 로그 조회 등 공개 결제 API 도구를 제공합니다. 공개 결제 흐름에는 판매자 키가 필요하지 않으며 관리자 작업도 노출하지 않습니다. 콜백 URL과 그 안의 비밀 nonce를 공유 프롬프트나 공개 출력에 포함하지 마세요.

개발 문서 보기

CryptAPI에서 이전하기

CryptAPI 연동을 Suawave로 이전하려면 어떻게 하나요?

API origin을 Suawave로 변경하고 새 주문과 입금 주소를 생성하세요. 콜백은 /pubkey/에서 받은 Suawave의 공개 키로 검증합니다. 전환 전에 지원 티커, 만료, 콜백 재시도, 미지원 파라미터를 확인하세요. CryptAPI의 공개 키나 IP 허용 목록을 재사용하지 마세요.

개발 문서 보기

제한, 만료, 환불

Suawave는 API 요청이나 새 입금 주소 생성을 제한하나요?

네. Suawave는 클라이언트 IP 및 콜백 호스트별 요청 제한과 새 티커 및 콜백 쌍 생성에 대한 별도 할당량을 적용합니다. HTTP 429 응답을 받으면 재시도 간격을 늘리고, Retry-After가 있으면 따르세요. 기존 쌍을 재사용하면 신규 생성 할당량은 소모하지 않지만 요청 제한에는 포함됩니다.

개발 문서 보기
Suawave에서 암호화폐 결제를 자동 환불할 수 있나요?

Suawave의 공개 API에는 결제자 환불 엔드포인트가 없으며, 초과 금액이나 지연 입금을 자동 반환하지 않습니다. 처리 가능한 결제가 이미 정산되었다면 쇼핑몰 자체 지갑에서 환불해야 합니다. 보류된 지연 전송은 수동 대조가 필요하며 자동 환불되지 않습니다.

개발 문서 보기
같은 Suawave 주소를 다시 생성하면 만료 시각이 연장되나요?

아니요. 기존 티커와 콜백 쌍으로 create를 반복하면 최초 입금 주소와 expires_at을 반환하며 만료는 연장되지 않습니다. 결제 화면에 반환된 UTC 만료 시각을 적용하고, 만료된 주소는 표시를 중단하세요. 새 주문에는 새 콜백 URL을 사용하세요.

개발 문서 보기