제품 통합 싱글 월렛 vs 트랜스퍼 월렛

싱글 월렛과 트랜스퍼 월렛

운영사의 플레이어 잔액을 게임 API에 연결하는 두 가지 월렛 모델의 기술 비교입니다. 자금을 누가 보관하는지, 베팅 중 어떤 호출이 오가는지, 장애를 어떻게 복구하는지, 운영사가 무엇을 구축해야 하는지를 다룹니다.

한눈에 비교

항목	싱글 월렛	트랜스퍼 월렛
잔액 보관	잔액은 운영사 DB에만 존재하며 게임사는 플레이어 자금을 보관하지 않습니다.	게임사가 별도의 게임 잔액을 보관하며 이체 호출로 자금을 넣고 뺍니다.
베팅 중 호출	모든 베팅과 당첨마다 운영사로 서버 간 콜백(잔액, 차감, 지급, 롤백)이 발생합니다.	없음. 게임은 게임사 측 잔액으로 진행되며 이체 입출금 시에만 호출이 발생합니다.
가용성 요구	월렛 엔드포인트는 모든 콜백에 보통 수백 ms 이내로 응답해야 하며, 장애 시 게임이 중단됩니다.	이체 시에만 필요하며 운영사 시스템이 잠시 오프라인이어도 라운드는 계속됩니다.
정합성 모델	운영사 원장이 실시간 단일 진실 원천이며, 잔액이 아닌 게임 라운드만 대사하면 됩니다.	두 개의 원장이 이체 시점에만 일치하므로 이체 단위 대사가 필요합니다.
장애 복구	타임아웃은 거래 ID 기반의 멱등 재시도와 롤백 호출로 해결합니다.	이체는 2단계(대기 후 성공 또는 실패)이며 결과가 불명확하면 상태 조회로 확인합니다.
연동 난이도	높음. 멱등성과 원장을 갖춘 저지연 콜백 서비스를 직접 구축하고 운영해야 합니다.	낮음. REST 엔드포인트 서너 개만 호출하면 되며, 인바운드 트래픽 보안과 확장 부담이 없습니다.
플레이어 경험	잔액이 하나이고 이체 단계가 없어 보너스, 크로스 프로덕트 플레이, 실시간 잔액 표시에 적합합니다.	플레이 전 입금, 종료 후 출금이 필요해 약간의 지연이 있고, 도중 이탈 시 잔액이 게임사에 남을 수 있습니다.
적합한 경우	자체 월렛이나 플랫폼이 있고 자금과 프로모션을 엄격히 통제하려는 운영사.	빠른 출시를 원하거나 실시간 월렛 서비스가 없는 운영사.

싱글 월렛(심리스)

싱글 월렛(심리스) 모델에서는 운영사 시스템이 곧 월렛입니다. 플레이어가 베팅하면 SSG API가 운영사의 콜백 엔드포인트를 호출하고, 운영사는 자체 원장의 잔액을 변경한 뒤 새 잔액을 응답합니다. 자금은 운영사 DB를 떠나지 않습니다.

호출 흐름

실행: 운영사 백엔드가 플레이어 ID와 세션 토큰으로 SSG에 게임 URL을 요청합니다.
베팅: 라운드마다 SSG가 고유 txId로 debit을 호출하고, 운영사는 잔액을 확인하고 원장에 기록한 뒤 새 잔액을 반환합니다.
당첨: 같은 라운드에 대해 SSG가 지급 금액(0일 수 있음)으로 credit을 호출합니다.
장애: 호출이 시간 초과되면 SSG가 같은 txId로 재시도하고, 재시도 한도를 넘으면 rollback을 보냅니다.

콜백 메서드(예시)

메서드	용도	주요 필드	멱등
`balance`	플레이어의 현재 잔액을 반환합니다.	`playerId, currency`	예(읽기 전용)
`debit`	베팅: 금액을 차감합니다.	`playerId, txId, roundId, gameId, amount, currency`	txId 기준
`credit`	당첨 정산: 금액을 지급합니다.	`playerId, txId, roundId, amount, currency`	txId 기준
`rollback`	오류 후 이전 차감 또는 지급을 취소합니다.	`txId, refTxId`	txId 기준

debit 요청 예시

{
  "method": "debit",
  "playerId": "p_839201",
  "txId": "tx_20261007_000184",
  "roundId": "r_77f3a1",
  "gameId": "slots_fruit_01",
  "currency": "MYR",
  "amount": "2.50",
  "ts": 1791338577,
  "sign": "hex(HMAC-SHA256(secret, canonical))"
}

응답 예시

{
  "status": "OK",
  "txId": "tx_20261007_000184",
  "balance": "97.50",
  "currency": "MYR"
}
// errors: INSUFFICIENT_FUNDS, PLAYER_NOT_FOUND,
//         DUPLICATE_TX (return original result), INTERNAL_ERROR

월렛 서비스가 지켜야 할 규칙

멱등성: 같은 txId의 debit 또는 credit이 다시 오면 원래 결과를 반환하고 자금을 다시 움직이면 안 됩니다. txId에 고유 인덱스를 두어 보장하세요.
원자적 원장 기록: 잔액 확인, 원장 행 삽입, 잔액 갱신을 하나의 DB 트랜잭션으로 처리해 동시 베팅으로 인한 초과 인출을 막으세요.
debit보다 먼저 온 rollback: 원래 debit이 타임아웃되어 본 적 없는 txId의 rollback이 먼저 도착할 수 있습니다. 표식을 저장해 늦게 도착하는 같은 txId의 debit을 거부하세요.
지연 목표: 네트워크 포함 p99 500ms 미만을 목표로 하세요. 콜백 경로는 인덱스 읽기 1회와 쓰기 1회로 제한하고 리포트 쿼리는 분리하세요.
금액 형식: 금액은 십진 문자열 또는 정수 최소 단위로 다루고 부동소수점은 쓰지 마세요. 통화가 플레이어 계정과 일치하는지 검증하세요.
보너스와 프리 스핀: 프리 스핀은 금액 0의 debit 뒤에 당첨금 credit이 오는 형태입니다. 원장에서 프로모션 잔액과 현금 잔액을 분리하세요.
보안: 정규화된 요청에 대한 HMAC-SHA256 서명을 검증하고, 오래된 타임스탬프를 거부하며, SSG 발신 IP만 허용하고, TLS 1.2 이상을 요구하세요.
정산 대사: SSG의 일일 라운드 리포트를 roundId 기준으로 원장과 대조하세요. 차이는 누락된 콜백이나 롤백에서 발생합니다.

트랜스퍼 월렛

트랜스퍼 월렛 모델에서는 게임사가 플레이어별 게임 잔액을 보관합니다. 운영사 백엔드가 플레이 전에 자금을 넣고 이후에 뺍니다. 플레이 중에는 운영사로 콜백이 오지 않으므로 아웃바운드 REST 호출만 필요합니다.

호출 흐름

입금: 운영사 백엔드가 고유 txId와 금액으로 transferIn을 호출하며 결과는 PENDING 또는 SUCCESS입니다.
플레이: 게임을 실행합니다. 모든 베팅과 당첨은 게임사 측 잔액만 변경하며 운영사로 콜백되지 않습니다.
출금: 플레이어가 떠나면 전체 잔액에 대해 transferOut을 호출하고, SUCCESS가 되면 운영사 원장에 반영합니다.
결과 불명: 이체 호출이 시간 초과되면 다른 작업 전에 같은 txId로 getTransferStatus를 조회하세요.

API 메서드(예시)

메서드	용도	주요 필드	멱등
`transferIn`	운영사 월렛에서 플레이어 게임 잔액으로 자금을 이동합니다.	`playerId, txId, amount, currency`	txId 기준
`transferOut`	게임 잔액에서 운영사 월렛으로 자금을 되돌립니다.	`playerId, txId, amount \| all`	txId 기준
`getBalance`	플레이어 게임 잔액을 조회합니다.	`playerId`	예(읽기 전용)
`getTransferStatus`	txId의 상태(PENDING, SUCCESS, FAILED)를 반환합니다.	`txId`	예(읽기 전용)

운영사 백엔드가 지켜야 할 규칙

의도당 txId 하나: 첫 호출 전에 txId를 만들고 모든 재시도에 재사용하세요. 이전 건의 상태를 알기 전에는 새 txId를 만들지 마세요.
내 원장 먼저 차감: 입금 시 SSG 호출 전에 원장에서 금액을 예약하고, 상태가 확정되면 확정하거나 해제하세요.
잔류 잔액 회수: 게임 잔액이 있으나 활성 세션이 없는 플레이어를 찾아 출금하는 배치를 돌리세요. 도중에 브라우저를 닫은 경우를 처리합니다.
롤링과 리포트: 베팅을 실시간으로 볼 수 없으므로 콜백이 아닌 SSG에서 가져온 라운드 리포트로 롤링, 보너스 조건, 리스크 한도를 계산하세요.
정산 대사: 모든 입출금을 txId 기준으로 SSG 기록과 대조하고, 타임아웃보다 오래된 PENDING에 알림을 거세요.
보안: HMAC-SHA256으로 요청에 서명하고, TLS 1.2 이상으로만 호출하며, API 키는 비밀 저장소에 보관하고, SSG를 호출할 수 있는 서버를 제한하세요.

장애 시나리오

시나리오	싱글 월렛	트랜스퍼 월렛
네트워크 타임아웃	베팅 중 SSG가 같은 txId로 재시도하고 한도 후 rollback을 보냅니다. 운영사는 멱등해야 합니다.	이체만 영향을 받습니다. 같은 txId로 getTransferStatus를 조회한 뒤 처리하세요.
운영사 시스템 중단	플레이어가 라운드를 시작하거나 이어갈 수 없으며 진행 중 라운드는 롤백됩니다.	플레이어는 기존 게임 잔액으로 계속 플레이할 수 있고 새 이체는 차단됩니다.
중복 요청	해당 txId의 저장된 응답을 반환하고 아무것도 변경하지 않습니다.	해당 txId의 저장된 결과를 반환하고 아무것도 변경하지 않습니다.
라운드 중 연결 끊김	라운드는 게임사에서 정상 종료되고 credit이 평소대로 전송됩니다.	라운드가 종료되고 자금은 출금 또는 회수 배치 전까지 게임 잔액에 남습니다.
잔액 불일치	대개 누락된 콜백이나 롤백 때문이며 roundId 기준 라운드 리포트 대조로 찾습니다.	대개 잔류하거나 대기 중인 이체 때문이며 txId 기준 이체 대조로 찾습니다.

어떤 모델을 선택할까

다음의 경우 싱글 월렛을 선택

이미 실시간 월렛 또는 원장 서비스를 운영하고 있습니다.
스포츠북, 카지노, 프로모션에서 하나의 잔액을 써야 합니다.
리스크, 보너스 조건, 책임 게임 한도를 위해 실시간 베팅 데이터가 필요합니다.
팀이 고가용성의 저지연 서비스를 운영할 수 있습니다.

다음의 경우 트랜스퍼 월렛을 선택

최소한의 개발로 빠르게 출시하고 싶습니다.
아직 실시간 월렛 서비스가 없습니다.
공개 콜백을 보호할 필요 없이 아웃바운드 호출만 쓰고 싶습니다.
잔액이 잠시 남는 것을 감수할 수 있고 회수 배치를 돌릴 수 있습니다.

많은 운영사가 먼저 트랜스퍼 월렛으로 출시하고, 자체 월렛 서비스가 준비되면 싱글 월렛으로 전환합니다. 단계적 전환 방법은 문의해 주세요.

연동 체크리스트

자금이 움직이는 모든 호출에 txId 고유 인덱스와 멱등 처리 적용
HMAC 서명 검증, 타임스탬프 허용 범위, IP 허용 목록
소수 안전한 금액 처리와 통화 검증
샌드박스에서 지연된 재시도를 포함한 타임아웃, 재시도, 롤백 테스트
roundId(싱글) 또는 txId(트랜스퍼) 기준 일일 대사 배치
모니터링과 알림: 콜백 지연, 오류율, 대기 이체, 잔류 잔액

연동 엔지니어와 상담

샌드박스를 함께 살펴보고 플랫폼에 맞는 모델 선택을 도와드립니다. 연동은 7일 이내 완료를 보장합니다.

이메일 문의 텔레그램 문의 제품 통합으로 돌아가기

sales@ssggaming.com