balance — 잔액 조회

플레이어의 현재 잔액을 조회합니다. 돈을 움직이지 않는 유일한 콜백이며, 실패해도 재시도하지 않습니다.

POST {wallet_base_url}/balance

언제 호출되나

시점	설명
게임 화면 진입	플레이어가 실행 URL 로 들어와 로비 · 게임 화면이 처음 뜰 때. 최근 10초 안에 받은 잔액이 있으면 그 값을 쓰고 호출하지 않습니다
잔액 새로고침	플레이어가 화면에서 잔액을 새로 고칠 때. 접속 하나당 10초에 한 번까지
연결 확인	연동 신청 뒤 플랫폼이 연결 · 서명을 시험할 때 (연결 확인)

debit · credit · rollback 응답의 balance 도 플랫폼이 플레이어 화면에 바로 반영하므로, 베팅 · 정산 때마다 balance 를 따로 부르지는 않습니다. 게임 실행(POST /launch) 때도 부르지 않습니다.

요청

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

필드	타입	필수	설명
external_id	string	●	오퍼레이터 쪽 플레이어 ID
player_id	string | null	●	플랫폼 플레이어 ID(pl_…), 참고용. 연결 확인 호출에서는 null
currency	string	●	플레이어 통화 (예: PHP)
operator_session_id	string | null	●	게임 실행 때 보낸 값. 없었으면 null

POST /wallet/balance HTTP/1.1
Host: api.example-casino.com
Content-Type: application/json; charset=utf-8
X-Operator: acme
X-Timestamp: 1792547400123
X-Nonce: Q2x7mN0pR4sT8vW1yZ3bC5dE
X-Signature: 5f0c1e9a…(64자 hex)

{"currency":"PHP","external_id":"u-102938","operator_session_id":"s-88af21","player_id":"pl_0199e8b4f2a37c1d8e5b6a4f3c2d1e0b"}

응답

필드	타입	필수	설명
status	string	●	OK 또는 오류 status
balance	integer	OK 일 때 ●	현재 잔액, 최소 단위 정수

성공

{ "status": "OK", "balance": 1250000 }

플레이어 없음

{ "status": "PLAYER_NOT_FOUND" }

통화 불일치

{ "status": "CURRENCY_MISMATCH" }

서명 오류

{ "status": "INVALID_SIGNATURE" }

status	언제 쓰나
OK	잔액을 돌려줄 때. balance 를 꼭 넣습니다
PLAYER_NOT_FOUND	external_id 에 해당하는 플레이어가 없을 때
CURRENCY_MISMATCH	요청 currency 가 플레이어 통화와 다를 때
INVALID_SIGNATURE	서명 검증에 실패했을 때
INVALID_REQUEST	external_id 가 비었거나 본문이 깨졌을 때
UNKNOWN_ERROR	그 밖의 내부 오류

차단된 플레이어라도 잔액 조회에는 OK 를 돌려줘도 됩니다. 베팅을 막는 것은 debit 의 PLAYER_BLOCKED 입니다.

플랫폼 동작

결과	플랫폼 처리
OK + balance	잔액을 화면에 표시하고 10초 동안 기억
OK 인데 balance 없음	실패로 처리
OK 가 아닌 status, 3초 타임아웃, HTTP 200 아님, 연결 실패	최근 10초 안에 알던 잔액이 있으면 그 값을 표시하고, 없으면 잔액을 비워 두거나(화면 진입) 새로고침 실패(WALLET_UNAVAILABLE)를 알림

• 재시도하지 않습니다. 잔액 조회 실패는 베팅을 막지 않습니다 — 베팅 가능 여부는 debit 결과로만 정해집니다.
• balance 는 잔액을 바꾸면 안 됩니다. 읽기 전용으로 구현하세요.