한 번의 연동으로
123게임을 내 서비스에
플레이어 잔액은 파트너사가 그대로 보유하고, 123게임은 베팅과 당첨이 발생할 때마다 파트너사의 지갑 API를 호출합니다. 별도의 충전이나 잔액 이전 없이 안전하게 게임을 제공할 수 있습니다.
연동 흐름
파트너 백엔드가 123 Gateway에 세션 발급을 요청합니다.
POST /sw/launch응답받은 launch_url을 iframe 또는 새 화면으로 엽니다.
launch_url베팅·당첨 시 123이 파트너 지갑을 호출합니다.
bet · win · rollback연동 준비 사항
<GATEWAY_URL>123 API 기본 주소
<OPERATOR_ID>파트너사 고유 식별자
<SECRET_KEY>HMAC 서명용 공유 비밀키
https://partner.example/api/game파트너사가 구현할 지갑 주소
게임 실행 요청과 서명 생성은 반드시 서버에서 수행해야 합니다. Git 저장소, JavaScript, 모바일 앱 코드, 공개 문서에 비밀키를 포함하면 안 됩니다.
HMAC-SHA256 서명
게임 실행 요청과 모든 지갑 콜백은 같은 방식으로 서명합니다. JSON을 다시 가공하지 말고 전송하거나 수신한 원본 body 바이트를 사용해야 합니다.
HMAC_SHA256(SECRET_KEY, TIMESTAMP + "\n" + RAW_BODY)| 필수 헤더 | 값 |
|---|---|
| X-SW-Operator | 발급받은 Operator ID |
| X-SW-Timestamp | Unix epoch 밀리초 |
| X-SW-Signature | hex 소문자 HMAC 결과 |
| Content-Type | application/json |
<?php
$timestamp = (string) floor(microtime(true) * 1000);
$rawBody = json_encode($payload, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac(
'sha256',
$timestamp . "\n" . $rawBody,
getenv('SW_SECRET_KEY')
);타임스탬프 허용 오차는 ±30초입니다. 운영 서버의 시간을 NTP로 동기화하세요.
게임 실행
<GATEWAY_URL>/sw/launch| 필드 | 필수 | 설명 |
|---|---|---|
| player_id | 필수 | 파트너사의 플레이어 고유 ID |
| game | 필수 | chart 또는 rabbit |
| currency | 선택 | 계약된 통화 코드 |
| lang | 선택 | ko, en, ja, zh_cn, vi, th, fil |
| return_url | 선택 | 게임 종료 후 복귀 주소 |
| token | 권장 | authenticate에서 돌려받을 플레이어 세션 토큰 |
{
"player_id": "user-1234",
"game": "chart",
"currency": "KRW",
"lang": "ko",
"return_url": "https://partner.example/lobby",
"token": "one-time-player-session"
}{
"launch_url": "<ISSUED_GAME_URL>"
}launch_url은 짧은 유효시간을 가진 세션 주소입니다. 저장하거나 공유하지 말고 즉시 게임 화면에 사용하세요.
지갑 콜백 API 5종
파트너사는 아래 5개 POST 경로를 구현하고 Wallet Base URL을 123 담당자에게 전달해야 합니다. 123은 등록된 주소로 HMAC 서명 요청을 보냅니다.
/authenticate플레이어 인증token으로 플레이어를 확인하고 ID·통화·잔액을 반환
/balance잔액 조회현재 플레이어의 사용 가능한 잔액을 반환
/bet베팅 차감잔액을 검사한 뒤 amount만큼 차감
/win당첨 지급당첨 또는 환불 금액을 플레이어 잔액에 지급
/rollback거래 취소ref_key가 가리키는 기존 베팅 차감을 복원
{
"status": "ok",
"tx_ref": "partner-tx-10001",
"balance": "99000",
"currency": "KRW",
"player_id": "user-1234"
}{
"status": "error",
"error_code": "insufficient_funds"
}지원 오류: insufficient_funds · player_not_found · tx_not_found
멱등성 처리
(operator_id, idempotency_key)를 유니크하게 저장하세요. 같은 키의 요청이 다시 오면 잔액을 재처리하지 않고 최초 응답을 그대로 반환해야 합니다.
| 상황 | 콜백 | 잔액 처리 |
|---|---|---|
| 베팅 | bet | 베팅액 차감 |
| 당첨 | win | 당첨금 지급 |
| 무승부·환불 | win | 베팅액 지급 |
| 라운드 무효·처리 불확정 | rollback | 원 베팅 차감 복원 |
차트게임 결과는 비동기로 정산되며 라운드 종료 후 수초~수분 뒤 win이 도착할 수 있습니다.
베팅내역 조회
게임 세션의 플레이어 베팅내역을 읽기 전용으로 조회합니다. 자금 이동은 없으며 다른 플레이어의 내역은 조회할 수 없습니다.
<GATEWAY_URL>/sw/bets?limit=50&before=<id>sw_sess=<token>X-SW-Session: <token>?s=<token>{
"ok": true,
"currency": "KRW",
"bets": [{
"id": 10432,
"game": "chart",
"round_no": "319",
"round_id": "BTCUSDT:60:...",
"side": "UP",
"stake": "5000",
"payout": "9370",
"status": "WON",
"result": "win"
}],
"next_before": 10432
}오픈 전 체크리스트
연동을 시작할 준비가 되셨나요?
담당자에게 Wallet Base URL과 테스트 환경 정보를 전달하면 데모 인증정보를 발급해드립니다.