[POST] 밸런스 트랜잭션 요청

META에서 에이전트 측 서버로 호출하는 API입니다. 유저 잔액을 증감시키며, 변경 후의 잔액을 반환합니다. 에이전트는 이 API를 구현하고 요청 정보를 기반으로 잔액을 갱신해야 합니다.

POST {에이전트 wallet_api_url}/changeBalance

Body

username _String_required

에이전트 측에서 유일한 유저를 식별하기 위한 고유 사용자 이름입니다.

amount _Number _required

잔액 증감 금액입니다. 양수, 음수, 0 모두 가능합니다. 에이전트는 모든 트랜잭션에 대해 부호에 관여하지 않고 increment 연산으로 처리해야 합니다.

type _Enum _required

Allowed values: BET, WIN, CANCEL, DEBIT_EXCEED_WIN, ADJUST, REWARD

에이전트는 이 필드를 기준으로 취해야할 행동을 구분해야 합니다.

transaction _Object _required

META에 기록되는 트랜잭션 정보입니다. 일부 필드들은 에이전트의 응답을 받은 후 갱신됩니다.

transaction object description

id _Number _required

META 시스템의 트랜잭션 고유 ID 입니다. 이 ID를 사용하여 멱등성을 보장하길 권장합니다.

Caution: type이 CANCEL 일 경우에도, 이 값은 취소할 트랜잭션의 body.transaction.id 가 아닌 META 시스템의 트랜잭션 고유 ID 입니다.

previous_tx_id _{Number or null} _required

이 필드가 null이 아닌 경우, 이 요청은 previous_tx_id에 해당하는 ID를 가진 트랜잭션의 연관된 트랜잭션 입니다.

type _Enum _required

Allowed values: BET, WIN, CANCEL, DEBIT_EXCEED_WIN, ADJUST, REWARD

에이전트는 이 필드를 기준으로 취해야할 행동을 구분해야 합니다.

created_at _{String <date-time>} _required

context Object

트랜잭션이 발생한 맥락을 담고있습니다.

Mandatory when: BET, WIN, CANCEL, DEBIT_EXCEED_WIN

Optional when: ADJUST, REWARD

context.game_id _Number _required

유저가 플레이중인 게임의 게임 식별자입니다.

context.round_id _String _required

라운드 식별자입니다. 에이전트는 이 값을 기준으로 게임 트랜잭션 (BET, WIN, CANCEL_BET, CANCEL_WIN)을 그룹화해야 합니다.

동일한 round_id에 대해 여러 번의 트랜잭션이 발생할 수 있으며 (타입과 관계없이), 그 트랜잭션들은 모두 동일한 라운드에 속합니다.

context.game_title _String _required

context.brand _String _required

context.game_type _Enum _required

Allowed values: LIVE_CASINO, SLOT

Body example

^{BET 트랜잭션 예시}

{
  "username": "부산의달",
  "amount": -5000,
  "type": "BET",
  "transaction": {
    "id": 257,
    "type": "BET",
    "context": {
      "game_id": 961,
      "round_id": "1954499662388264960",
      "game_title": "Gem Saviour",
      "brand": "PgSoft",
      "game_type": "SLOT"
    },
    "created_at": "2025-08-10T11:06:49.445Z",
    "previous_tx_id": null
  }
}

^{WIN 트랜잭션 예시}

body.transaction.previous_tx_id는 연관된 BET트랜잭션의 body.transaction.id입니다.

{
  "username": "부산의달",
  "amount": 2000,
  "type": "WIN",
  "transaction": {
    "id": 261,
    "type": "WIN",
    "context": {
      "game_id": 961,
      "round_id": "1954499662388264960",
      "game_title": "Gem Saviour",
      "brand": "PgSoft",
      "game_type": "SLOT"
    },
    "created_at": "2025-08-10T11:06:49.474Z",
    "previous_tx_id": 257
  },
  "agent_id": 5
}

_{CANCEL 트랜잭션 예시}

body.transaction.previous_tx_id는 취소할 BET트랜잭션의 body.transaction.id입니다.

{
  "username": "부산의달",
  "amount": 5000,
  "type": "CANCEL",
  "transaction": {
    "id": 260,
    "type": "CANCEL",
    "context": {
      "game_id": 961,
      "round_id": "1954499662388264960",
      "game_title": "Gem Saviour",
      "brand": "PgSoft",
      "game_type": "SLOT"
    },
    "created_at": "2025-08-10T11:06:49.474Z",
    "previous_tx_id": 257
  }
}

^{DEBIT_EXCEED_WIN 의 원본 트랜잭션 예시 ( 최대 당첨금 제한 5,000원 설정 )} 게임사에게 WIN 트랜잭션에 대해 올바른 밸런스 수정 후 정상 응답을 반환해야 하므로, 최대 당첨금 제한(max_win)이 설정된 상태라도, 회원에게는 우선 전액을 지급해야 합니다.

이후, META와 에이전트 내에서 초과 당첨금 회수 처리(DEBIT_EXCEED_WIN)를 별도로 진행해야 합니다.

(DEBIT_EXCEED_WIN - 2 에서 계속)

{
  "username": "부산의달",
  "amount": 8250,
  "type": "WIN",
  "transaction": {
    "id": 999, 
    "type": "WIN",
    "context": {
      "game_id": 123,
      "round_id": "752929388000",
      "game_title": "Gates of Olympus 1000",
      "brand": "PragmaticPlay",
      "game_type": "SLOT"
    },
    "created_at": "2025-06-17T03:29:44.151Z",
    "previous_tx_id": 998
  }
}

^{DEBIT_EXCEED_WIN 트랜잭션 예시 ( 최대 당첨금 제한 5,000원 설정 )}

초과 당첨금 회수 트랜잭션 처리 흐름

에이전트가 META 백오피스에서 최대 당첨금 제한을 설정한 이후, 유저가 제한을 초과하는 당첨금을 획득했을 때 본 트랜잭션이 발생합니다.

회수 처리는 아래 순서로 진행됩니다:

원본 당첨금 전액을 일반적인 WIN 트랜잭션으로 처리하여 지급합니다.
원본 당첨금 - 당첨금 제한 만큼의 회수 요청을 META가 에이전트에 전송합니다.
에이전트는 해당 요청을 수신 후, 유저로부터 초과 금액을 회수합니다.

body.transaction.previous_tx_id는 원본 WIN 트랜잭션의 body.transaction.id 값을 가집니다.

{
  "username": "부산의달",
  "amount": -3250,
  "type": "DEBIT_EXCEED_WIN",
  "transaction": {
    "id": 1000,
    "type": "DEBIT_EXCEED_WIN",
    "context": {
      "game_id": 123,
      "round_id": "752929388000",
      "game_title": "Gates of Olympus 1000",
      "brand": "PragmaticPlay",
      "game_type": "SLOT"
    },
    "created_at": "2025-06-17T03:29:44.217Z",
    "previous_tx_id": 999
  }
}

Response

Name

Type

Description

success*

boolean

트랜잭션 처리의 성공 또는 실패를 나타냅니다.

balance

Number

트랜잭션을 처리한 후의 유저 밸런스

success: true 일 경우 필수로 요구됩니다.

소숫점 6자리까지 허용 가능합니다.

error

String

응답 실패 또는 트랜잭션 거부의 원인

success: false 일 경우 필수로 요구됩니다.

success: false를 응답할 경우, 적절한 error를 응답에 포함해야 실패 원인을 디버깅할 수 있습니다.

Response example

{
    "success": true,
    "balance": 320094.55
}

Previous[GET] 유저 밸런스 조회 NextTransfer API 연동 가이드

Last updated 6 months ago

Was this helpful?

hashtagResponse

Response