연동 체크리스트

운영 전환 전에 오퍼레이터 쪽에서 확인할 항목입니다. 검수 때 이 목록을 기준으로 함께 점검합니다.

서명 · 보안

[ ] 콜백 서명을 원문 본문 바이트로 검증하고, X-Operator · 타임스탬프(±5분) · 상수 시간 비교를 모두 한다.
[ ] 콜백 nonce 를 5분 이상, 여러 서버가 공유하는 저장소에 보관해 재사용을 거절한다.
[ ] 리버스 프록시가 경로를 바꾸더라도 등록된 지갑 URL 의 원래 경로로 서명을 검증한다.
[ ] 업무 결과는 거절을 포함해 모두 HTTP 200 + 본문 status 로 돌려준다.
[ ] 응답 balance 는 처리 후 잔액이고, 통화 최소 단위 정수다.
[ ] tx_id 멱등: 이미 처리한 tx_id 가 다시 오면 잔액을 다시 바꾸지 않고 처음과 같은 응답(거절이었으면 같은 거절)을 돌려준다.
[ ] 같은 플레이어의 거래를 동시에 처리해도 잔액이 꼬이지 않는다(DB 트랜잭션 · 행 잠금).
[ ] 응답 시간이 충분히 짧다 — 플랫폼은 balance · debit 을 3초, credit · rollback 을 5초 기다린다.
[ ] 지갑 원장에 tx_id · round_id · reason · amount · 처리 결과를 남겨 대사할 수 있다.

[ ] 잔액이 모자라면 차감하지 않고 INSUFFICIENT_FUNDS 를 돌려준다.
[ ] 차단 · 자기 배제 중인 플레이어는 PLAYER_BLOCKED 로 거절한다.
[ ] 이미 rollback 이 먼저 도착한 tx_id 의 debit 이 늦게 오면 차감하지 않고 TX_ALREADY_ROLLED_BACK 을 돌려준다.
[ ] debit 이 타임아웃 · HTTP 오류 · UNKNOWN_ERROR 로 끝나면 플랫폼이 debit 을 재시도하지 않고 곧바로 rollback 을 보낸다는 것을 전제로 구현했다.
[ ] reason(bet · ante · double · split · buy_in · top_up)을 원장에 남긴다.

[ ] 금액 0 인 credit(패배한 라운드 정산)을 정상 처리하고 OK 를 돌려준다.
[ ] 차단된 플레이어에게도 credit 을 반영한다(진행 중이던 판의 당첨 · 캐시아웃).
[ ] credit 은 OK 가 아니면 상태와 관계없이 계속 재시도된다는 것을 알고, 정상 거래에 OK 외의 상태를 돌려주지 않는다.
[ ] 재시도 간격(1초 → 2초 → 5초 → 15초 → 1분 → 5분, 이후 5분마다)으로 같은 tx_id 가 반복돼도 한 번만 반영된다.

[ ] ref_tx_id 로 원 debit 을 찾는다.
[ ] 원 debit 이 성공했으면 그 금액을 되돌리고 OK.
[ ] 원 debit 기록이 없으면(debit 이 닿지 않음) 아무것도 되돌리지 않고 OK 를 돌려주며, 그 ref_tx_id 를 기록해 늦게 오는 debit 을 거절한다.
[ ] 원 debit 이 이미 되돌려졌거나 거절됐으면 다시 되돌리지 않고 OK.
[ ] rollback 도 OK 가 아니면 계속 재시도된다는 것을 전제로 구현했다.
[ ] reason(cancel_bet · round_void · timeout · system)을 원장에 남긴다.

검수 때 테스트 지갑에 일부러 장애를 넣어 확인하면 좋습니다.

[ ] POST /launch 를 오퍼레이터 서버에서만 부른다.
[ ] 플레이어가 누를 때마다 launch_url 을 새로 받고(60초 · 1회용), 받은 그대로 연다.
[ ] 새 창은 클릭 처리기 안에서 바로 열고, noopener 를 쓰지 않는다.
[ ] iframe 으로 넣는다면 임베드 도메인을 등록했고, game.closed 를 받으면 iframe 을 닫는다.
[ ] return_url 을 보내거나 기본 복귀 URL 이 등록돼 있다(없으면 postMessage 가 오지 않는다).
[ ] postMessage 를 받을 때 event.origin 과 data.source === "games-platform" 을 확인한다.
[ ] external_id 는 플레이어마다 바뀌지 않는 값이고, 64바이트 이하다.
[ ] nickname 을 2~16자로 맞춰 보낸다.
[ ] 플레이어 통화가 고정된다는 것(CURRENCY_MISMATCH)을 반영했다.
[ ] operator_session_id 에 로그인 토큰 원문 대신 불투명한 ID 를 쓴다.
[ ] PLAYER_BLOCKED · GAME_MAINTENANCE · TABLE_NOT_FOUND 같은 실행 오류를 플레이어에게 알맞게 안내한다.

[ ] 사이트 로그아웃 · 자기 배제 · 계정 정지 때 POST /players/{external_id}/logout 를 부른다(정지는 block: true).
[ ] 정지를 풀 때 block: false 로 다시 부른다.

[ ] GET /transactions 로 기간별 지갑 거래를 받아 자기 지갑 원장과 tx_id 단위로 맞춰 본다(정기 작업).
[ ] 대사에서 pending · uncertain 상태 거래를 따로 살핀다.
[ ] 베팅 내역 화면이 필요하면 GET /rounds · GET /rounds/{round_id} 를 쓴다.
[ ] prepaid 운영이면 GET /credit 로 알 잔액을 감시하고, 경고 기준(warn_below) 아래로 내려가기 전에 충전을 요청한다.
[ ] Operator API 의 429 · 5xx 에 대기 후 재시도한다(쓰기 요청은 결과를 먼저 조회).
[ ] 장애 · 대사 불일치 때 연락할 담당자와 경로를 정했다.