debit — 출금

베팅 · 착석 때 플레이어 잔액에서 금액을 차감합니다. 플랫폼은 debit 을 재시도하지 않습니다. 결과가 불확실하면 실패로 보고 곧바로 rollback 을 보냅니다.

POST {wallet_base_url}/debit

언제 호출되나

reason	언제	round_id	게임
bet	베팅	rnd_…	바카라 · 블랙잭 · 스피드 홀덤
ante	앤티	rnd_…	스피드 홀덤
double	더블 다운	rnd_…	블랙잭
split	스플릿	rnd_…	블랙잭
buy_in	테이블 착석(바이인)	tss_…	바이인형 게임 (홀덤 · 오마하 · 라이브 홀덤 · 맞고 · 고스톱 · 섯다 · 통잇 · 레드독)
top_up	앉은 채로 칩 추가	tss_…	바이인형 게임

• 베팅형 게임은 한 라운드에 debit 이 여러 번 올 수 있습니다. 같은 라운드의 debit 은 같은 round_id 를 씁니다.
• 바이인형 게임은 핸드마다 debit 하지 않습니다. 착석 · 칩 추가 때만 옵니다.
• 새로운 reason 값이 추가될 수 있습니다. 모르는 값이 와도 거절하지 말고 일반 출금으로 처리하세요.

요청

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

필드	타입	필수	설명
tx_id	string	●	플랫폼 거래 ID(tx_ + 32자리 hex). 멱등 키
external_id	string	●	오퍼레이터 쪽 플레이어 ID
player_id	string	●	플랫폼 플레이어 ID(pl_…), 참고용
currency	string	●	통화 코드
amount	integer	●	차감할 금액, 최소 단위 정수, 1 이상
reason	string	●	위 표의 값
game_code	string	●	게임 코드
table_id	string	●	테이블 ID (tbl_…)
round_id	string	●	라운드 ID(rnd_…) 또는 테이블 세션 ID(tss_…)
operator_session_id	string | null	●	게임 실행 때 보낸 값. 없었으면 null
created_at	string	●	플랫폼이 거래를 만든 시각 (UTC, 밀리초)

베팅 (바카라)

{
  "amount": 5000,
  "created_at": "2026-10-19T02:10:00.123Z",
  "currency": "PHP",
  "external_id": "u-102938",
  "game_code": "live_baccarat",
  "operator_session_id": "s-88af21",
  "player_id": "pl_0199e8b4f2a37c1d8e5b6a4f3c2d1e0b",
  "reason": "bet",
  "round_id": "rnd_0199f2a0b1c27d3e8f4a5b6c7d8e9f01",
  "table_id": "tbl_0199a1b2c3d47e5f8a9b0c1d2e3f4a5b",
  "tx_id": "tx_0199f2a1c3d47e8b9a6f1e2d3c4b5a69"
}

착석 (홀덤)

{
  "amount": 100000,
  "created_at": "2026-10-19T02:12:41.507Z",
  "currency": "PHP",
  "external_id": "u-102938",
  "game_code": "holdem_nlh",
  "operator_session_id": "s-88af21",
  "player_id": "pl_0199e8b4f2a37c1d8e5b6a4f3c2d1e0b",
  "reason": "buy_in",
  "round_id": "tss_0199f29e7c6b4a5d8e3f2a1b0c9d8e7f",
  "table_id": "tbl_0199a1b5d0e47f2a9b8c7d6e5f4a3b2c",
  "tx_id": "tx_5a3c9e1f0b7d4e2a8c6f1b3d5e7a9c0e"
}

실제 본문은 공백 없는 한 줄 JSON 입니다. 위 예시는 읽기 쉽게 줄을 나눴습니다.

응답

필드	타입	필수	설명
status	string	●	결과 코드
balance	integer	OK 일 때 ●	차감 후 잔액
operator_tx_id	string		오퍼레이터 쪽 거래 ID

성공

{ "status": "OK", "balance": 1245000, "operator_tx_id": "w-99812" }

잔액 부족

{ "status": "INSUFFICIENT_FUNDS", "balance": 3000 }

차단된 플레이어

{ "status": "PLAYER_BLOCKED" }

늦게 도착

{ "status": "TX_ALREADY_ROLLED_BACK" }

처리 여부 불명

{ "status": "UNKNOWN_ERROR" }

status 별 플랫폼 동작

status	오퍼레이터가 쓸 때	플랫폼 처리
OK	차감했을 때 (같은 tx_id 재요청이면 처음 결과)	베팅 · 착석 확정, 응답 balance 를 화면에 반영
INSUFFICIENT_FUNDS	잔액이 amount 보다 적을 때	거절 확정. 플레이어에게 잔액 부족으로 안내
LIMIT_EXCEEDED	오퍼레이터의 책임 도박 한도(베팅 · 손실 한도 등)를 넘을 때	거절 확정. 플레이어에게 한도 초과로 안내
PLAYER_BLOCKED	차단 · 자기 배제 중일 때	거절 확정
PLAYER_NOT_FOUND	플레이어가 없을 때	거절 확정
CURRENCY_MISMATCH	요청 통화가 플레이어 통화와 다를 때	거절 확정
TX_ALREADY_ROLLED_BACK	이 tx_id 의 rollback 을 먼저 받았을 때	거절 확정
INVALID_REQUEST	필드 누락 · 형식 오류, 같은 tx_id 인데 내용이 다를 때	거절 확정
INVALID_SIGNATURE	서명 검증 실패	거절 확정
UNKNOWN_ERROR	차감했는지 확실하지 않은 오류	실패 처리 + 즉시 rollback(timeout)
(3초 타임아웃 · HTTP 200 아님 · 연결 실패 · 잘못된 JSON · 빈 status)	—	실패 처리 + 즉시 rollback(timeout)

• 거절 확정이면 플랫폼은 rollback 을 보내지 않습니다. 거절 status 는 잔액을 건드리지 않은 게 확실할 때만 쓰세요.
• 위 표에 없는 status 값은 거절 확정으로 처리됩니다. 처리 여부가 불확실하면 반드시 UNKNOWN_ERROR 나 HTTP 5xx 로 응답하세요.
• 거절된 베팅 · 착석은 플레이어 화면에 오류로 표시됩니다. 잔액 부족 · 한도 초과는 그 사유가 그대로 보이고, 그 밖의 사유는 게임에 따라 지갑 오류(WALLET_UNAVAILABLE)로 묶여 보일 수 있습니다.
• 거절 응답의 balance 는 넣어도 되고 빼도 됩니다. 플랫폼은 거절 응답의 잔액을 쓰지 않습니다.

처리 순서

권장 순서입니다. 잔액 차감과 거래 기록은 한 DB 트랜잭션 안에서 합니다.

1. 서명 검증 → 실패면 INVALID_SIGNATURE
2. 필드 검증(tx_id · external_id 존재, amount 가 1 이상의 정수) → 실패면 INVALID_REQUEST
3. 같은 tx_id 기록이 있으면 → 저장된 응답을 그대로 반환 (성공 · 거절 모두)
4. 플레이어 행 잠금 → 없으면 PLAYER_NOT_FOUND
5. 이 tx_id 가 롤백 표시(rollback 이 먼저 왔던 기록)에 있으면 → TX_ALREADY_ROLLED_BACK
6. 통화 확인 → CURRENCY_MISMATCH
7. 차단 · 자기 배제 → PLAYER_BLOCKED, 책임 도박 한도 → LIMIT_EXCEEDED
8. 잔액 확인 → INSUFFICIENT_FUNDS
9. 차감하고 OK + 차감 후 balance + operator_tx_id

거절 결과도 tx_id 로 기록해 두고, 같은 tx_id 가 다시 오면 같은 거절을 돌려주세요.

주의

3초 안에 응답하세요

debit 응답을 3초 안에 받지 못하면 플랫폼은 베팅 · 착석을 거절하고 같은 금액의 rollback(reason: "timeout", ref_tx_id = 이 debit)을 곧바로 보냅니다. 오퍼레이터 쪽에서 debit 이 늦게라도 처리됐다면 그 rollback 으로 환원해야 하고, debit 이 아직 처리 중이라면 rollback 과 겹칠 수 있습니다. 두 요청을 플레이어 단위 잠금 안에서 처리하고, 롤백 표시 확인(5단계)은 잠금을 잡은 뒤에 하세요. 자세한 경우는 rollback 을 보세요.

같은 debit 은 두 번 오지 않지만, 대비는 하세요

플랫폼은 한 번 보낸 debit 을 다시 보내지 않습니다. 그래도 오퍼레이터 앞단의 프록시 · 로드밸런서가 요청을 다시 보내는 경우가 있으므로 3단계 멱등 처리를 꼭 구현하세요.

착석 직후 이석

바이인형 게임에서 debit 결과가 오기 전에 플레이어가 자리를 떠나면, 플랫폼은 성공한 바이인 금액을 별도의 credit(reason: "cash_out", 다른 tx_id)으로 돌려줍니다. debit 을 취소(rollback)하는 것이 아니므로 그대로 반영하면 됩니다.