암호화폐 결제의 부족 입금, 초과 입금, 지연 및 중복 전송 처리

정확한 금액 기록, 입금 건별 수수료, 검증된 Suawave 콜백을 바탕으로 암호화폐 부족 입금, 초과 금액, 만료 주문, 중복을 처리하세요.

게시일 , 수정일

파란색과 빨간색 유리 구슬이 서로 다른 수량으로 담긴 그릇으로 표현한 암호화폐 부족 입금과 초과 입금

암호화폐 부족 입금에 대응하려면 고객 문의에 답하기 전에 금액 정책부터 정해야 합니다. 주문 합계, 선택한 티커, 최소 입금액을 저장하세요. 정확한 금액을 사용해 처리 가능한 확정 입금을 한 번씩만 반영합니다. 초과 입금, 만료된 주소, 반복 웹훅은 각각 다른 판단이 필요하고 모두 콜백을 생성하는 것도 아니므로 구분해 처리하세요.

Suawave의 공개 주소 생성 API에는 쇼핑몰 주문 합계를 전달하지 않습니다. 티커와 콜백 URL에 입금 주소를 할당할 뿐입니다. 검증된 입금이 25 USDT 구매 대금을 충족하는지는 쇼핑몰에서 결정합니다. 게이트웨이는 각 전송의 정산 가능 여부를 판단합니다.

결제 화면에서 부족 입금을 어떻게 처리해야 하나요?

먼저 주문 합계보다 적게 보낸 경우와 게이트웨이 최소 금액 미만인 전송을 구분하세요. 25 USDT 주문에 20 USDT를 입금하면 정산 대상이 될 수 있어도 주문은 미결제 상태로 남을 수 있습니다. 티커의 최소 금액 미만인 전송은 정산되지 않고 콜백도 발생하지 않으며 공개 로그에도 나타나지 않습니다. 두 경우를 같은 대기 상태로 취급하면 안 됩니다.

GET /{ticker}/info/ 또는 create 응답에서 minimum_transaction_coin을 읽으세요. 구매자가 보내기 전에 표시하고 추가 입금을 안내하기 전에도 다시 확인하세요. 각 전송에는 처음 감지된 시점에 유효한 최소 금액을 적용합니다.

결제 상황 게이트웨이 동작 쇼핑몰의 처리
처리 가능한 입금이 주문 합계보다 적음 자체 수수료와 확정 콜백을 갖고 개별 정산 입금을 기록하고 남은 금액은 미결제 유지
입금액이 티커 최소 금액 미만 정산과 공개 콜백 없음 최소 금액 안내 및 지원을 통한 조사
처리 가능한 입금이 주문 합계를 초과 수수료 차감 후 처리 대상 입금 전액 정산 초과 금액을 기록하고 쇼핑몰 정책 적용
같은 웹훅 재전달 같은 이벤트 UUID 유지 효과를 반복하지 않고 수신 확인

게이트웨이 기준은 수수료와 최소 금액 가이드에 정의되어 있습니다. 이후 상품 가격이 바뀌어도 기존 결제에 영향을 주지 않도록 쇼핑몰의 결제 인정 기준은 주문과 함께 저장하세요.

고객이 부족한 금액을 나중에 보낼 수 있나요?

주문이 여전히 처리 가능한 상태라면 추가 입금을 보낼 수 있지만, 각 입금이 독립적으로 티커의 최소 금액을 충족해야 합니다. Suawave는 조건에 맞는 입금을 개별 정산합니다. 최소 금액 미만의 조각 입금을 합쳐 하나의 처리 가능한 전송으로 만들지 않습니다.

25 USDT 주문에 구매자가 먼저 20 USDT를 보낸 경우를 생각해 보세요. 부족한 5 USDT는 TRON USDT의 기본 최소 입금액인 10.00 USDT보다 적습니다. “남은 5 USDT를 보내세요”라고 안내하면 두 번째 전송도 최소 금액 미만이 되는 문제가 생깁니다. BEP20 USDT의 기본 최소 입금액은 1.00 USDT이지만, 안내 전에는 실제 API 값을 확인하세요.

부족한 금액이 현재 최소 금액보다 적으면 고객과 금액 문제를 해결할 수 있는 담당자에게 주문을 연결하세요. 초과 입금을 만든다는 사실을 알리지 않은 채 더 큰 금액의 전송을 자동 요청하면 안 됩니다. 정확한 금액을 표시하고 전송 확인 전에 출금 시 차감되는 금액을 살펴보도록 안내하면 이런 문제를 상당 부분 예방할 수 있습니다.

주문에 반영하는 금액에서 수수료를 빼야 하나요?

쇼핑몰 정책의 기준으로 총입금액 또는 순정산액 중 하나를 선택하고 명확히 표시하세요. value_coin은 들어온 입금액입니다. value_forwarded_coin은 fee_coin의 총수수료를 차감한 뒤 정산 주소에 도착한 금액입니다.

총입금액을 인정하는 쇼핑몰은 순정산액이 더 적더라도 조건에 맞는 25 USDT 입금으로 25 USDT 주문을 결제 완료 처리할 수 있습니다. 순수령액을 요구한다면 같은 입금도 부족할 수 있습니다. value_forwarded_coin은 이미 수수료를 뺀 값이므로 fee_coin을 다시 차감하지 마세요.

금액은 정수 단위나 정확한 십진수 타입으로 변환하기 전까지 십진수 문자열로 유지하세요. 레지스트리에서 TRON USDT는 소수점 6자리, BSC USDT는 18자리입니다. 모든 USDT 티커가 소수점 6자리를 쓴다고 가정하면 네트워크별 금액 파싱이 잘못됩니다.

고객이 암호화폐를 초과 입금하면 어떻게 되나요?

공개 결제 흐름은 처리 대상 입금에서 수수료를 차감한 전액을 정산합니다. 쇼핑몰 예상 합계에서 입금액을 제한하거나 차액을 송신자에게 자동 환불하지 않습니다. 25 USDT 주문에 30 USDT를 입금했다면 추가 5 USDT의 처리는 쇼핑몰에서 결정해야 합니다.

금액 정책에 따라 최초 입금액, 순정산액, 초과 금액을 기록하세요. 주문을 결제 완료로 표시해도 초과 금액이 기록에서 사라져서는 안 됩니다. 지원 담당자가 남은 조치를 알 수 있도록 별도의 해결 상태를 유지하세요.

txid_in을 안전한 환불 목적지의 증거로 취급하지 마세요. 결제자가 거래소나 다른 서비스에서 보냈다면 발신 주소가 개인 수신 주소가 아닐 수 있습니다. 별도 반환을 하기 전에 자체 고객 절차로 목적지를 받고 확인하세요. Suawave의 공개 create API는 환불 API가 아닙니다.

실제 입금이 두 건이면 고객이 두 번째 입금을 실수라고 설명하더라도 결제는 두 건입니다. 각각 확정 콜백과 수수료가 발생할 수 있습니다. 주문이 결제된 뒤 들어온 두 번째 결제는 두 번째 배송 대신 초과 입금 기록을 생성해야 합니다.

예시 주문 기록 금액 또는 판단
주문 합계 25 USDT
받은 입금 20 USDT
남은 미결제 금액 5 USDT
TRC20 추가 입금 안내 남은 금액이 기본 최소 입금액보다 적으므로 자동 요청하지 않음

주문 만료 후의 암호화폐 결제는 어떻게 되나요?

create는 expires_at을 반환합니다. 같은 티커와 콜백 쌍으로 create를 반복해도 최초 만료 시각을 반환하며 기한을 연장하지 않습니다. 만료 후에는 기존 입금 주소 표시를 중단하세요. 구매자가 다시 시도하려면 별도 콜백 URL을 사용하는 새 주문을 생성하세요.

공개 API의 기본 만료 시간은 24시간이지만, 배포 환경에도 이 기본값이 적용되었다고 가정하지 말고 반환된 타임스탬프를 사용하세요. 게이트웨이에는 기본 2분의 유예 시간도 설정되어 있습니다. 이는 처리 가능 여부를 판단할 때의 허용 범위이며 고객에게 추가 결제 시간으로 안내할 값이 아닙니다.

Suawave는 관측 시각과 블록 타임스탬프에 설정된 시계 오차 허용치를 더한 값 중 더 이른 값을 전송의 유효 시각으로 사용합니다. 마감 이후 확정되었다는 사실만으로 지연 전송이 되지는 않습니다. 쇼핑몰의 콜백 수신 시각 대신 전송 시각과 설정된 유예 시간이 처리 가능 여부를 결정합니다.

유효 시각이 만료 시각에 유예 시간을 더한 시점 이상이면 검토를 위해 입금을 보류합니다. 금액에 반영하거나 자동 정산하지 않으며, 공개 pending 또는 확정 콜백도 발생하지 않고 공개 로그에도 나타나지 않습니다. 게이트웨이가 자동 환불하거나 쇼핑몰 주문을 완료하지도 않습니다. 지원 담당자가 주문 정보와 트랜잭션 해시로 조사해야 합니다.

운영자가 나중에 보류 자금을 판매자에게 보내면 어떻게 되나요?

운영자가 정산 주소로 수동 sweep을 수행해도 공개 콜백은 보내지 않습니다. 지원 과정에서 이런 방식으로 지연 입금 보류를 해결했다면 쇼핑몰은 수동으로 대조해야 합니다. 모든 보류 결제가 결국 자동으로 결제 완료 상태가 된다고 약속하면 안 됩니다.

기존 주문과 대체 주문은 구분해서 유지하세요. 티커와 콜백 쌍의 연결은 고정되므로 만료된 콜백 URL을 다시 사용해도 다른 주소를 받을 수 없습니다. 이 식별 규칙은 주소 생성 레퍼런스를 참고하세요.

중복 결제와 중복 웹훅은 어떻게 구분하나요?

중복 웹훅은 기존 이벤트를 다시 전달한 것입니다. 재시도는 uuid를 유지하므로 영속 저장소의 고유성 제약으로 반복 처리를 막을 수 있습니다. 중복 결제는 실제로 이루어진 별도의 전송입니다. 첫 전송과 금액이 정확히 같아도 별도 결제 기록이 필요합니다.

pending 콜백과 확정 콜백은 서로 다른 UUID를 사용합니다. 새로운 UUID를 모두 추가 금액으로 세면 한 입금을 두 번 반영하게 됩니다. 인정된 확정 합계에는 확정 이벤트만 더해야 하며, 입금 기록에는 pending과 확정 상태 간의 연결을 유지해야 합니다.

콜백은 순서가 바뀌어 도착할 수도 있습니다. 이미 확정을 기록했다면 늦게 온 pending 이벤트가 입금을 대기 상태로 되돌려서는 안 됩니다. 감지와 정산 확정이 다른 이벤트인 이유는 암호화폐 결제 최종성에서 설명합니다.

데이터베이스 트랜잭션에는 무엇을 포함해야 하나요?

검증된 확정 콜백에 대해 이벤트 UUID를 삽입하고 입금을 기록하세요. 해당 주문을 잠근 상태에서 인정 합계를 다시 계산하고, 그에 따른 주문 상태 전이를 같은 트랜잭션에 저장하세요. UUID가 이미 있으면 금액을 더하거나 추가 배송을 예약하지 않고 정상 수신 확인을 반환합니다.

주문당 영속적인 이행 작업도 하나만 허용하세요. 서로 다른 실제 결제가 동시에 도착해 둘 다 금액 기준을 충족할 수 있습니다. 이벤트 중복 제거만으로는 각 요청이 배송을 시도하는 것을 막지 못합니다. 주문 잠금과 고유한 이행 작업으로 이 경쟁 상태를 방지하세요. 이는 쇼핑몰의 연동 설계이며 Suawave create 엔드포인트의 추가 파라미터가 아닙니다.

판단 대상 처리 방향
이미 저장된 이벤트 UUID 효과를 반복하지 않고 수신 확인
최소 금액 미만의 입금 자동 합산하지 않고 지원을 통해 확인
허용 시간을 벗어난 전송 보류 내역 수동 대조
주문 금액보다 부족한 확정 합계 잔액을 미결제로 유지
주문 금액을 초과한 확정 합계 초과 금액을 기록하고 별도 해결

합계가 맞지 않으면 지원 담당자는 무엇을 확인해야 하나요?

저장된 콜백 URL로 원래 주문의 로그를 조회하고 전체 URL은 비공개로 유지하세요. 해당 URL 자체가 로그 조회 권한 역할을 합니다. 처리 대상 항목을 기록된 확정 이벤트와 비교하세요. sent는 정산이 확정되었으나 확정 콜백의 수신 확인이 없다는 뜻이고, done은 해당 콜백의 수신 확인까지 완료되었다는 뜻입니다.

로그가 비어 있다고 해서 돈을 보내지 않았다는 뜻은 아닙니다. 최소 금액 미만, 미지원, 지연 전송은 없을 수 있습니다. 트랜잭션 해시와 선택한 네트워크를 받아 목적지와 시각을 확인하세요. 콜백 핸들러에 이벤트가 없다는 이유만으로 고객에게 다시 결제하라고 안내하지 마세요.

결제 변경 사항을 공개하기 전에 부분 결제, 초과 결제, 두 번째 실제 입금, 같은 이벤트의 반복 전달로 금액 정책을 확인하세요. 서명과 수신 확인 경로는 웹훅 처리 가이드를 참고하세요. 네트워크 최소 금액 때문에 소액 주문의 지원 요청이 너무 많다면 USDT TRC20과 BEP20 비교를 바탕으로 먼저 제공할 경로를 다시 검토하세요.