연동 안내

1. B·C: 가맹점 서버에서 서명 프로그램 init → 출력된 xpub 를 운영자에게 전달 (A 는 받는 주소)
2. 운영자가 가맹점 등록 → 담당자 이메일로 설정 링크 수신
3. 링크에서 비밀번호·OTP 설정 → API 키·웹훅 시크릿·서명 프로그램 토큰 한 번 표시 (보관)
4. 대시보드 › 웹훅 › 연동 설정: 웹훅 주소, 결제 팝업 사이트
5. 서버에서 주문 만들기 → 팝업 → 웹훅으로 지급
6. B·C: 서명 프로그램 run 상시 실행 (집금·이동·출금 서명)

Authorization: Bearer sk_...
결제 서버: https://pay.usdtgate.net

API 키는 가맹점 서버에만. 브라우저·앱에 넣지 않음. 유출 시 대시보드 › 웹훅 › API 키 재발급 (기존 키 즉시 무효).

요청

curl -X POST https://pay.usdtgate.net/v1/orders \
  -H "Authorization: Bearer sk_..." -H "Content-Type: application/json" \
  -d '{"order_id":"chg-1001","amount":"50000","currency":"KRW","customer_ref":"user-77"}'

응답

{
  "id": "ord_...", "order_id": "chg-1001", "status": "pending",
  "network": "TRC20", "address": "T...", "address_index": 12,
  "amount": "36.24", "paid": "0", "remaining": "36.24",
  "currency": "KRW", "fiat_amount": "50000", "rate": "1379.7", "credit": "0",
  "result": null, "expires_at": "...Z",
  "pay_url": "https://pay.usdtgate.net/pay/ord_...", "tg_url": "..."
}

<script src="https://pay.usdtgate.net/checkout.js"></script>
<script>
GwPay.open(order.id, {
  onPaid: d => reloadBalance(),
  onStatus: d => {},
  onClose: d => {},
  lang: 'ko',
  theme: 'simple'  // simple · night · card
});
</script>

대시보드에 등록한 결제 팝업 사이트에서만 열림. theme 생략 = 대시보드 › 연동 설정 › 결제 화면 값. 팝업 알림은 화면 갱신용 · 지급은 웹훅으로만.

POST (가맹점 웹훅 주소)
X-Gw-Timestamp: 1762650000
X-Gw-Signature: hex(HMAC-SHA256(whsec_..., timestamp + "." + body))

{"id": "evt_...", "type": "order.paid", "created": "...Z", "data": { ...주문 }}

서명·시각(5분) 확인 후 200 응답. 실패 시 2ⁿ분 간격 8회 재전송, 같은 id. 대시보드 › 웹훅에서 다시 보내기.

검증 (Python)

from gateway_sdk import verify_webhook
if not verify_webhook(WHSEC, request.headers, request.get_data()):
    abort(400)

order.partial·order.paid 마다 credit_delta(이번 입금분, 주문 통화)를 웹훅 id 당 한 번 더함. credit = 합계.

주문 응답의 주소가 내 키에서 나온 것인지 고객에게 보여주기 전에 확인. 결제 서버가 털려도 고객 돈이 다른 곳으로 가지 않음.

from gateway_sdk import check_order
check_order(order, xpub=MY_XPUB)            # B·C
check_order(order, fixed_address=MY_ADDR)   # A
# 다르면 AddressMismatch → 주문 중단

모든 웹훅은 id 당 한 번만 반영. 충전 비율·게임머니 단위는 가맹점이 정함. 세 흐름 전부 들어 있는 예: server.js (Node.js), 충전 주문형: flask_shop.py.

otp = 서명 프로그램 OTP (대시보드 OTP 와 별개). 120초 안에 서명 프로그램이 가져가야 함.

자동 출금: 서명 설정 payout.auto_max_per_tx·auto_max_per_day 안에서만 OTP·텔레그램 승인 없이 서명 (기본 0 = 꺼짐, 넘으면 rejected). 출금 지갑 잔액은 내부 이동(OTP)으로 미리 채워 둘 것.

자동 출금 sig: HMAC-SHA256(auto_secret, ref + "|" + to + "|" + 금액×1000000) 16진수 소문자. 예: ref wd-1 · 12.5 USDT → "wd-1|T…|12500000". auto_secret 은 서명 프로그램 설정 payout.auto_secret 과 가맹점 서버에만 둠 (게이트웨이에 보내지 않음, agent.py init 이 만들어 줌). 서명 불일치·같은 ref 재사용은 rejected. API 키나 게이트웨이가 털려도 sig 없이는 자동 출금 불가.

가맹점 서버에서 실행. 키는 가맹점 서버에만 있고 결제 서버는 서명할 수 없음. 나가는 연결만 사용.

unzip signer.zip && cd signer
pip install -r requirements.txt
cp signer_config.example.json signer_config.json
python agent.py init signer_config.json   # 키 파일·OTP·xpub 출력 → xpub 운영자에게
# signer_config.json: gateway_url = https://pay.usdtgate.net, signer_token = st_...
python agent.py run signer_config.json    # 상시 실행
python selftest_signer.py

대상: 완료 주문, 주문 없는 고객 입금, 만료 뒤 입금, 완료 출금. 내역은 대시보드 › 주문 › 수수료 내역 (CSV). 송금 기록은 작업 목록 kind=fee, 웹훅 job.updated.