R-Live Games API

한국어

English

한국어

English

화면 모드

credit — 입금 ​

라운드 정산 · 이석 때 플레이어 잔액에 금액을 더합니다. 플랫폼은 credit 을 OK 를 받을 때까지 재시도하므로, 오퍼레이터는 같은 tx_id 를 한 번만 반영하고 어떤 경우에도 OK 로 끝내야 합니다.

http
POST {wallet_base_url}/credit

언제 호출되나 ​

reason언제round_idamount
settle베팅형 게임(바카라 · 블랙잭 · 스피드 홀덤)의 라운드 정산rnd_…돌려받는 원금을 포함한 총 지급액. 지면 0
cash_out바이인형 게임에서 자리를 떠날 때(이석 · 접속 끊김 정리 · 테이블 종료 · 강제 로그아웃), 그리고 아래 환불tss_…남은 칩 전부. 다 잃었으면 0 일 수 있음

  • settle 은 그 라운드에 확정된 베팅이 있는 플레이어마다 정확히 한 번 옵니다. 당첨이 없어도 amount: 0 으로 보내므로, 이 credit 으로 플레이어의 라운드가 끝났음을 알 수 있습니다. 베팅을 모두 취소한 플레이어에게는 오지 않습니다. 라운드가 무효가 되면 credit 대신 rollback(round_void)이 옵니다.

  • cash_out 은 보통 테이블 세션(tss_…) 하나에 한 번이지만, 다음 경우에는 같은 테이블 세션에 다른 tx_id 의 cash_out 이 더 올 수 있습니다.

    • 바이인 · 칩 추가 debit 이 성공했는데 그 결과가 오기 전에 플레이어가 자리를 떠난 경우 — 그 금액을 돌려줌
    • 라이브 홀덤 핸드가 무효가 됐는데 플레이어 좌석이 이미 정리된 경우 — 그 핸드에 낸 칩을 돌려줌

    테이블 세션당 credit 이 한 번이라고 가정하지 말고 tx_id 로만 중복을 판단하세요.

  • 레이크(수수료)는 credit 에서 이미 빠진 금액입니다. 따로 지갑 거래가 생기지 않습니다.

  • 새로운 reason 값이 추가될 수 있습니다. 모르는 값이 와도 입금으로 처리하세요.

요청 ​

헤더는 공통 헤더와 같습니다.

필드타입필수설명
tx_idstring●플랫폼 거래 ID. 멱등 키
external_idstring●오퍼레이터 쪽 플레이어 ID
player_idstring●플랫폼 플레이어 ID(pl_…), 참고용
currencystring●통화 코드
amountinteger●지급액, 최소 단위 정수, 0 이상
reasonstring●settle 또는 cash_out
game_codestring●게임 코드
table_idstring●테이블 ID (tbl_…)
round_idstring●라운드 ID(rnd_…) 또는 테이블 세션 ID(tss_…)
round_closedboolean●이 credit 으로 플레이어의 라운드(테이블 세션)가 끝났는지. 현재는 모든 credit 이 true 입니다
operator_session_idstring | null●게임 실행 때 보낸 값. 없었거나 플랫폼 복구 경로면 null
created_atstring●플랫폼이 거래를 만든 시각 (UTC, 밀리초). 재시도해도 바뀌지 않음
json
{
  "amount": 30000,
  "created_at": "2026-10-19T02:10:41.004Z",
  "currency": "PHP",
  "external_id": "u-102938",
  "game_code": "live_baccarat",
  "operator_session_id": "s-88af21",
  "player_id": "pl_0199e8b4f2a37c1d8e5b6a4f3c2d1e0b",
  "reason": "settle",
  "round_closed": true,
  "round_id": "rnd_0199f2a0b1c27d3e8f4a5b6c7d8e9f01",
  "table_id": "tbl_0199a1b2c3d47e5f8a9b0c1d2e3f4a5b",
  "tx_id": "tx_8e2b4d6f1a3c5e7b9d0f2a4c6e8b1d3f"
}
json
{
  "amount": 182000,
  "created_at": "2026-10-19T03:05:17.880Z",
  "currency": "PHP",
  "external_id": "u-102938",
  "game_code": "holdem_nlh",
  "operator_session_id": "s-88af21",
  "player_id": "pl_0199e8b4f2a37c1d8e5b6a4f3c2d1e0b",
  "reason": "cash_out",
  "round_closed": true,
  "round_id": "tss_0199f29e7c6b4a5d8e3f2a1b0c9d8e7f",
  "table_id": "tbl_0199a1b5d0e47f2a9b8c7d6e5f4a3b2c",
  "tx_id": "tx_c4e6a8b0d2f41a3c5e7b9d1f3a5c7e9b"
}
json
{
  "amount": 0,
  "created_at": "2026-10-19T02:11:39.412Z",
  "currency": "PHP",
  "external_id": "u-102938",
  "game_code": "live_baccarat",
  "operator_session_id": "s-88af21",
  "player_id": "pl_0199e8b4f2a37c1d8e5b6a4f3c2d1e0b",
  "reason": "settle",
  "round_closed": true,
  "round_id": "rnd_0199f2a3e5c17a9b8d6f4e2c0a1b3d5f",
  "table_id": "tbl_0199a1b2c3d47e5f8a9b0c1d2e3f4a5b",
  "tx_id": "tx_1f3d5b7a9c0e2f4a6b8d0c2e4f6a8b0d"
}

응답 ​

필드타입필수설명
statusstring●OK 여야 끝납니다
balanceinteger●입금 후 잔액. amount: 0 이면 현재 잔액
operator_tx_idstring오퍼레이터 쪽 거래 ID
json
{ "status": "OK", "balance": 1275000, "operator_tx_id": "w-99813" }

플랫폼 동작 ​

결과플랫폼 처리
OK확정. 응답 balance 를 플레이어 화면에 반영
OK 가 아닌 모든 status (PLAYER_NOT_FOUND · PLAYER_BLOCKED · INVALID_REQUEST · INVALID_SIGNATURE 포함)재시도
5초 타임아웃 · HTTP 200 아님 · 연결 실패 · 잘못된 JSON재시도

재시도 간격은 1초 → 2초 → 5초 → 15초 → 1분 → 5분이고, 그 뒤로는 5분마다 기한 없이 보냅니다. 재시도 본문은 처음과 바이트 단위로 같습니다(created_at 포함). 서명 헤더만 새로 만듭니다.

credit 은 거절할 수 없습니다

credit 에 OK 가 아닌 응답을 주면 그 거래는 끝나지 않고 계속 재시도됩니다. 다음 경우에도 반영하고 OK 를 돌려주세요.

  • 플레이어가 차단 · 자기 배제 중이거나 로그아웃 · 세션 만료된 경우 — 돈을 돌려주는 거래입니다.
  • operator_session_id 가 null 이거나 이미 끝난 세션인 경우 — 세션 값으로 검사하지 마세요.
  • amount 가 0 인 경우 — 잔액을 바꾸지 말고 현재 잔액으로 OK.
  • 같은 tx_id 가 다시 온 경우 — 다시 더하지 말고 처음 응답 그대로 OK.

처리 순서 ​

  1. 서명 검증 → 실패면 INVALID_SIGNATURE (재시도되므로 원인을 바로 고쳐야 합니다)
  2. 필드 검증(tx_id · external_id 존재, amount 가 0 이상의 정수) → 실패면 INVALID_REQUEST
  3. 같은 tx_id 기록이 있으면 → 저장된 응답을 그대로 반환
  4. 플레이어 행 잠금
  5. amount 만큼 더하고(0 이면 그대로) OK + 입금 후 balance + operator_tx_id
  6. 응답과 함께 tx_id 기록

credit 은 취소(rollback) 대상이 아닙니다. 잘못된 지급이 의심되면 플랫폼과 운영 절차로 협의합니다.

주의 ​

  • 순서: 재시도 중인 credit 은 그 뒤에 생긴 같은 플레이어의 debit 보다 늦게 도착할 수 있습니다. 도착 순서에 의존하지 마세요.
  • 플레이어를 지우지 마세요: 오퍼레이터가 플레이어 계정을 삭제해 PLAYER_NOT_FOUND 가 나면 그 플레이어의 미처리 credit 이 끝나지 않습니다. 탈퇴 처리 뒤에도 지갑 콜백을 받을 수 있게 계정 기록을 남겨 두세요.
  • 대사: 플랫폼 쪽 거래 상태는 GET /transactions 로 볼 수 있습니다. 재시도 중인 credit 은 status: "uncertain"(또는 pending)으로 보입니다.

문서 v1.0.0 · Operator API v1