사용자 자산 업데이트
사용자 자산을 업데이트하며, 처리 결과로 변경 후 잔액을 반환합니다.
파트너는 본 API를 구현하여, 전달받은 요청 정보를 기반으로 사용자 자산을 갱신해야 합니다.
POST {파트너 Callback URL}/changeBalance
Body
username
String
✅
파트너 시스템에서 사용자를 고유하게 식별하기 위한 사용자명
amount
Number
✅
잔액 증감 금액이며, 양수·음수·0 모두 허용됩니다. 파트너는 입력된 값의 부호와 무관하게 모든 트랜잭션을 increment 연산으로 처리해야 합니다.
type
Enum
✅
트랜잭션 유형을 구분하는 값입니다. 사용 가능한 값은 BET, WIN, CANCEL, DEBIT_EXCEED_WIN, ADJUST, REWARD 입니다.
transaction
Object
✅
트랜잭션 정보가 HighEnd 플랫폼에 기록되며, 일부 필드는 에이전트의 응답 이후 갱신됩니다.
Transaction Object
트랜잭션에 대한 세부 정보를 담는 객체입니다.
id
Number
✅
HighEnd 플랫폼에서 발급하는 트랜잭션 고유 ID.
파트너는 멱등성 보장을 위해 해당 ID 사용을 권장합니다.
⚠️ 주의: type이 CANCEL인 경우에도 이 값은 취소 대상 트랜잭션의 body.transaction.id가 아닌 HighEnd 플랫폼의 고유 ID입니다.
previous_tx_id
Number | null
✅
값이 null이 아닐 경우, 본 요청은 previous_tx_id로 지정된 트랜잭션에 연계된 트랜잭션으로 간주됩니다.
type
Enum
✅
트랜잭션 유형.
허용 값: BET, WIN, CANCEL, DEBIT_EXCEED_WIN, ADJUST, REWARD.
파트너는 해당 값을 기준으로 적절한 처리 동작을 구분해야 합니다.
created_at
String <date-time>
✅
트랜잭션 생성 시각.
context
Object
조건부
트랜잭션이 발생한 맥락(Context).
필수: BET, WIN, CANCEL, DEBIT_EXCEED_WIN
선택: ADJUST, REWARD
Transaction Context Object
transaction.context에 포함되는 세부 필드입니다.
game_id
Number
✅
사용자가 현재 플레이 중인 게임의 고유 식별자.
round_id
String
✅
라운드를 구분하는 식별자.
에이전트는 round_id를 기준으로 게임 트랜잭션(BET, WIN, CANCEL_BET, CANCEL_WIN)을 그룹화해야 합니다.
하나의 round_id에 대해 여러 트랜잭션이 발생할 수 있으며, 유형과 관계없이 모두 동일한 라운드에 속합니다.
game_title
String
✅
게임 제목.
brand
String
✅
게임 제공 브랜드명.
game_type
Enum
✅
게임 유형.
허용 값: LIVE_CASINO, SLOT
Body example
BET 트랜잭션 예시
WIN 트랜잭션 예시
body.transaction.previous_tx_id는 연관된 BET트랜잭션의 body.transaction.id입니다.
CANCEL 트랜잭션 예시
body.transaction.previous_tx_id는 취소할 BET트랜잭션의 body.transaction.id입니다.
DEBIT_EXCEED_WIN 의 원본 트랜잭션 예시 ( 최대 당첨금 제한 5,000원 설정 )
게임사에게 WIN 트랜잭션에 대해 올바른 밸런스 수정 후 정상 응답을 반환해야 하므로,
최대 당첨금 제한(max_win)이 설정된 상태라도, 회원에게는 우선 전액을 지급해야 합니다.
이후, META와 에이전트 내에서 초과 당첨금 회수 처리(DEBIT_EXCEED_WIN)를 별도로 진행해야 합니다.
(DEBIT_EXCEED_WIN - 2 에서 계속)
DEBIT_EXCEED_WIN 트랜잭션 예시 ( 최대 당첨금 제한 5,000원 설정 )
초과 당첨금 회수 트랜잭션 처리 흐름
에이전트가 META 백오피스에서 최대 당첨금 제한을 설정한 이후, 유저가 제한을 초과하는 당첨금을 획득했을 때 본 트랜잭션이 발생합니다.
회수 처리는 아래 순서로 진행됩니다:
원본 당첨금 전액을 일반적인
WIN트랜잭션으로 처리하여 지급합니다.원본 당첨금 - 당첨금 제한 만큼의 회수 요청을 META가 에이전트에 전송합니다.
에이전트는 해당 요청을 수신 후, 유저로부터 초과 금액을 회수합니다.
body.transaction.previous_tx_id는 원본 WIN 트랜잭션의 body.transaction.id 값을 가집니다.
\
Response
success*
boolean
이 필드는 트랜잭션 처리가 성공했는지 또는 실패했는지를 나타냅니다.
balance
Number
이 필드는 트랜잭션 처리 완료 후의 사용자 잔액을 나타냅니다.
응답이 success: true인 경우 반드시 포함되어야 하며, 값은 소수점 6자리까지 지원됩니다.
error
String
이 필드는 응답 실패 또는 트랜잭션 거부의 원인을 나타냅니다.
응답이 success: false인 경우에는 필수적으로 포함되어야 합니다.
응답 값이 success: false인 경우, HighEnd 플랫폼이 실패 원인을 진단할 수 있도록 적절한 error 객체를 응답에 포함해야 합니다.
Response example
Last updated