연동 개요
R-Live 게임 플랫폼은 오퍼레이터(카지노 사이트)에 게임을 API 로 제공하는 B2B 서비스입니다. 이 페이지는 연동 구성 요소와 용어, 운영 방식을 한눈에 정리합니다.
구성
연동에는 세 가지 통로가 있습니다. 오퍼레이터가 구현해야 하는 것은 ① Operator API 호출과 ② 지갑 콜백 수신 두 가지이고, ③ 게임 화면은 플랫폼이 제공합니다.
┌──────────────────────┐ ① Operator API (HTTPS, 서명) ┌──────────────────────┐
│ │ ─────────────────────────────────▶ │ │
│ 오퍼레이터 서버 │ POST /operator/v1/launch 등 │ R-Live 게임 플랫폼 │
│ (사이트 백엔드) │ │ │
│ │ ◀───────────────────────────────── │ │
└──────────────────────┘ ② 지갑 콜백 (HTTPS, 서명) └──────────────────────┘
▲ POST {wallet_base_url}/debit 등 ▲
│ │
│ 사이트 화면 ③ 게임 화면 (새 창 / iframe)
│ launch_url 로 이동, WebSocket
┌──────────┴───────────────────────────────────────────────────────────┴──┐
│ 플레이어 브라우저 │
└─────────────────────────────────────────────────────────────────────────┘| 통로 | 방향 | 하는 일 | 문서 |
|---|---|---|---|
| ① Operator API | 오퍼레이터 서버 → 플랫폼 | 게임 실행 URL 발급, 게임 · 테이블 목록, 라운드 · 거래 내역 조회, 플레이어 강제 종료, 테이블 · 딜러 관리 | Operator API |
| ② 지갑 콜백 | 플랫폼 → 오퍼레이터 서버 | 잔액 조회(balance), 출금(debit), 입금(credit), 출금 취소(rollback) | 지갑 콜백 |
| ③ 게임 화면 | 플레이어 브라우저 ↔ 플랫폼 | 로비 · 게임 렌더링, 실시간 진행(WebSocket), 라이브 영상 | 게임 실행 흐름 |
- 플레이어 잔액의 원본은 오퍼레이터 지갑입니다(심리스 지갑). 플랫폼은 플레이어 머니를 따로 보관하지 않고, 돈이 움직일 때마다 지갑 콜백을 부릅니다.
- 게임 규칙 · 셔플 · 판정 · 정산은 모두 플랫폼 서버에서 이뤄집니다. 오퍼레이터는 결과를 지갑 콜백과 내역 API 로 받습니다.
- Operator API 와 지갑 콜백은 서버 간 통신입니다. API 자격증명은 브라우저에 두지 말고 오퍼레이터 서버에만 보관하세요. 브라우저는 오퍼레이터 백엔드를 거쳐 게임 실행을 요청합니다.
- 플랫폼에서 오퍼레이터로 보내는 서버 호출은 지갑 콜백 4종뿐입니다. 별도의 웹훅 · 이벤트 푸시는 없으며, 내역은 라운드 · 거래 API 로 조회합니다.
용어
| 용어 | 설명 |
|---|---|
| 오퍼레이터(operator) | 플랫폼과 계약해 게임을 제공받는 사이트. 오퍼레이터 코드(예: acme)로 구분하며, 모든 요청의 X-Operator 헤더에 싣습니다. |
플레이어 external_id | 오퍼레이터가 정한 플레이어 ID(1~64바이트 문자열). 플랫폼은 (오퍼레이터, external_id) 쌍으로 플레이어를 식별하고, 처음 실행할 때 플랫폼 플레이어 ID(pl_…)를 만들어 줍니다. 지갑 콜백에도 이 값이 그대로 실려 옵니다. |
| 세션(session) | 플레이어가 게임 화면에 들어와 만들어지는 플랫폼 세션. 실행 URL 1회 사용마다 하나씩 생기며 최대 12시간 유지됩니다. |
| 테이블 세션 | 바이인형 게임에서 한 번 착석해 일어날 때까지의 기간(tss_…). 바이인 · 충전 · 캐시아웃 지갑 거래가 이 단위로 묶입니다. |
| 라운드(round) | 게임 한 판(rnd_…). 베팅형 게임은 베팅 · 정산 지갑 거래가 라운드 단위로 묶입니다. |
tx_id | 지갑 거래 ID(tx_…). 플랫폼이 결정적으로 만들기 때문에 같은 거래를 재시도하면 같은 tx_id 로 다시 옵니다. 오퍼레이터는 이 값으로 중복 처리(멱등) 를 해야 합니다. |
launch_token | 게임 실행 URL 에 실린 1회용 토큰. 60초 안에 한 번만 쓸 수 있고, URL fragment(#token=…)에 실려 서버 로그 · Referer 에 남지 않습니다. |
| 알(선불 크레딧) | prepaid 운영 방식에서 오퍼레이터가 플랫폼에 미리 충전해 두는 크레딧. 베팅(debit)마다 그 금액만큼 차감되고 당첨 · 캐시아웃(credit)만큼 돌아옵니다. |
ID 형식, 금액 단위, 시각 형식은 공통 규약에 정리되어 있습니다.
운영 방식 (credit_mode)
오퍼레이터마다 계약 때 두 운영 방식 중 하나가 정해집니다. 현재 방식은 GET /credit 응답의 mode 로 확인할 수 있습니다.
| 항목 | prepaid (알방식) | independent (독립운영) |
|---|---|---|
| 선불 크레딧(알) | 사용. 베팅 debit 전에 알을 먼저 차감 | 사용하지 않음 |
| 알이 모자랄 때 | 지갑을 부르지 않고 베팅 · 착석이 거절됩니다(플레이어 화면 오류 OPERATOR_CREDIT_EXHAUSTED) | 해당 없음 |
| debit 실패 · rollback | 차감한 알을 되돌림 | 해당 없음 |
| credit(당첨 · 캐시아웃) | 그 금액만큼 알에 더함 | 해당 없음 |
| 전용 테이블 만들기 | 불가 | 가능 (플랫폼이 허용한 게임) |
| 딜러 카드 입력 기록 조회 | 불가 | 가능 |
| 프라이빗 테이블 | 불가 | 가능 (전용 라이브 홀덤 테이블) |
협의 사항
운영 방식, 알 충전 · 정산 방법, 수수료율은 계약 시 협의합니다.
제공 게임
게임은 상대에 따라 두 종류(kind)로 나뉩니다.
종류 (kind) | 설명 | 게임 예 |
|---|---|---|
table (P2P) | 플레이어끼리 겨루는 게임. 판 결과에서 레이크(수수료)가 공제됩니다. | 텍사스 홀덤, 오마하, 라이브 홀덤, 맞고, 섯다 |
round (뱅크형) | 하우스와 겨루는 게임. | 바카라, 블랙잭, 스피드 홀덤, 레드독 |
지갑 콜백이 오는 시점은 게임이 칩을 다루는 방식에 따라 두 가지입니다.
| 지갑 흐름 | debit | credit | 해당 게임 |
|---|---|---|---|
| 바이인형 | 착석 때 buy_in, 칩 충전 때 top_up | 자리에서 일어날 때 cash_out (테이블 세션당 1회) | 모든 table 게임, 레드독 |
| 베팅형 | 베팅마다 bet (게임에 따라 ante · double · split) | 라운드 정산 때 플레이어당 1회 settle (패배 시 금액 0) | 바카라, 블랙잭, 스피드 홀덤 |
바이인형 게임에서는 테이블에 앉아 있는 동안 판마다 지갑을 부르지 않습니다. 자세한 내용은 지갑 콜백을 보세요.
라이브 게임(딜러 영상)과 RNG 게임이 함께 있으며, 오퍼레이터별로 켜진 게임은 GET /games 로 확인합니다. 전체 게임 코드는 게임 코드를 보세요.
다음 단계
- 연동 절차 · 환경 — 발급받는 정보와 알려 줄 정보, 환경별 주소
- 인증 · 서명 — 양방향 HMAC 서명
- 게임 실행 흐름 — 플레이어를 게임 화면으로 보내기
- 지갑 콜백 — balance · debit · credit · rollback 구현
- 연동 체크리스트 — 운영 전환 전 점검