Callback
Callback 연동 가이드
Callback은 플랫폼과 파트너사(에이전트/운영사) 간 잔액 조회, 베팅, 정산 등 요청·응답을 실시간 동기화하기 위해 사용됩니다. 본 문서는 Callback 규칙, 응답 포맷, 트랜잭션 처리 방식 및 주요 고려사항을 정의합니다.
필수 구현 사항
Callback은 Seamless 지갑 방식을 구현할 때 반드시 적용해야 합니다.
지정된 모든 엔드포인트를 구현해야 하며, 응답 포맷과 예시가 정확히 일치해야 합니다.
동작 방식
게임 진행 시, HighEnd 서버는 등록된 Callback URL을 통해 파트너 서버로 요청을 전송합니다.
응답 시간은 300ms 이하를 권장하며, 반드시 1.5초 미만이어야 합니다.
응답 지연 시, 오류로 처리될 수 있습니다.
모든 통신 대기 시간은 1.5초 미만으로 제한해야 합니다.
보안 요구사항
콜백 엔드포인트는 화이트리스트 기반으로 관리해야 합니다.
등록되지 않은 IP에서의 접근을 차단하여 외부 위변조 요청을 방지해야 합니다.
화이트리스트 등록에 필요한 IP는 고객 센터를 통해 확인 후 적용해야 합니다.
동작 프로세스 상세
1. 게임 접속 시 (/balance)
유저가 사이트 접속 → 게임 실행 버튼 클릭
사이트(운영사) → HighEnd 플랫폼 → 카지노 서버 순서로 호출이 전달됩니다.
HighEnd 플랫폼은
/get-game-url또는/openAPI를 호출하여 카지노 게임 접속 URL을 반환합니다.
2. 잔고 동기화 (/balance)
카지노 서버가 유저 잔고 확인을 위해 HighEnd 플랫폼에 /balance 요청을 보냅니다.
HighEnd 플랫폼은 파트너가 등록한 Callback URL을 호출합니다.
예: https://{callback_url}/balance?username=test
파트너 서버는 해당 유저의 현재 잔고를 조회하여 JSON으로 반환해야 합니다.
반환된 값은 HighEnd 플랫폼을 거쳐 카지노 서버에 전달되고, 게임 화면에 유저 잔고로 표시됩니다.
3. 유저 베팅 / 승리 / 취소 처리 (/changeBalance)
게임 중 발생하는 베팅, 승리, 취소 요청은 모두 금액(amount) 증감 처리만 하면 됩니다.
파트너 서버는 요청받은 amount를 단순히 유저 잔고에 더하거나 빼주는 방식으로 처리합니다.
상세 베팅 내역은 실시간으로 전달되지 않으며, 별도의 API를 통해 조회가 필요합니다.
응답 규칙
success필드는 반드시 포함되어야 하며, 요청 처리 결과에 따라 다음 필드를 추가해야 합니다:success: true일 경우,balance필드 필수 → 처리된 후 현재의 잔액을 의미합니다.success: false일 경우,error필드 필수 → 처리 실패 또는 거부에 대한 명확한 에러 메세지를 포함해야 합니다.
⚠️ 에러 발생 또는 에이전트가 내부 규정에 의해 처리를 거부하더라도, 다음 두 가지 상황에서 HTTP 응답 코드는 200 또는 201로 처리해야 합니다:
요청 포맷이 올바르고 요청을 처리 가능하지만, 에이전트 측 도메인 로직 상 잔액 변경을 거부한 경우
처리는 실패했지만, handling 가능한 에러로 판단된 경우
위 경우,
success: false와 함께error를 포함하여 응답하면 됩니다.예시:
처리 성공:
처리 실패 (에러 메시지 포함):
멱등성 및 트랜잭션 처리
요청 또는 응답은 언제든 유실될 수 있습니다.
body.transaction.id는 HighEnd 플랫폼의 트랜잭션 고유 ID이며, 멱등성 보장을 위해 사용됩니다.동일한
body.transaction.id가 다시 전달된 경우:이전 요청에 대한 처리가 성공했다면, 변경 없이 현재 잔액을 반환해야 합니다.
이전 요청에 대한 처리가 실패했다면, 다시 시도 후 응답(성공/실패)을 반환해야 합니다.
잔액 증감 처리 방식
body.amount는 양수, 0, 음수 모두 가능하며, 반드시 increment 연산으로 처리해야 합니다.
트랜잭션 그룹화 기준
BET / WIN / CANCEL은 회원의 게임 플레이로 인해 발생한 트랜잭션입니다.
파트너 측에서 회원의 게임 기록을 저장하고자 할 경우, 위 세 가지 타입의 트랜잭션을 기록해야 합니다.
게임기록은 body.transaction.context.round_id를 기준으로 그룹화할 수 있습니다.
동일한 round_id에 대해 BET / WIN / CANCEL 트랜잭션이 여러 번 발생할 수 있습니다.
결과가 발생하지 않은, 대기 상태로 남아있는 트랜잭션 구별 방법
동일한 round_id에 대해 BET 트랜잭션만 존재하고, WIN, CANCEL 트랜잭션이 아무것도 없는 경우
해당 BET 트랜잭션은 아직 결과가 발생하지 않은 대기 상태의 트랜잭션입니다.
이와 같이 결과가 발생하지 않은 트랜잭션을 구별해야 하는 경우, 다음 조건을 확인하세요:
BET트랜잭션이 존재함.위
BET트랜잭션의round_id와 동일한round_id를 가진WIN,CANCEL트랜잭션이 아무것도 기록돼 있지 않음.
위 조건을 만족하는 트랜잭션은, 결과 미처리가 의심되는 상태입니다.
해당 트랜잭션을 발견했다면, 트랜잭션의 body.transaction.id 값과 함께 서비스 데스크로 문의 주세요.
참고로, body.transaction.previous_tx_id를 가진 트랜잭션은
해당 previous_tx_id와 일치하는 body.transaction.id를 가진 트랜잭션의 결과 트랜잭션을 의미합니다.
그러나 이 previous_tx_id를 기반으로 BET과 WIN를 참조하는 방식은 권장되지 않습니다, 이유는 다음과 같습니다:
BET에 대한WIN이 발생하지 않을 수 있으며, (Example: Pragmatic Play LIVE_CASINO 게임)하나의
BET트랜잭션에 여러 개의WIN트랜잭션이 대응할 수 있습니다. (Example: PgSoft SLOT 게임)
위 두 가지 case는 게임사의 처리 방식에 따라 발생하며, 정상적인 상황입니다. 그러므로 반드시
round_id로 판단해야 합니다.
CANCEL 트랜잭션 처리 시 주의사항
CANCEL 트랜잭션은 BET트랜잭션을 취소하기 위한 트랜잭션 입니다.
CANCEL 트랜잭션의 body.transaction.id는 취소할 BET트랜잭션의 body.transaction.id 가 아닙니다.
HighEnd 의 트랜잭션 고유 id 입니다. CANCEL 트랜잭션 또한 다른 트랜잭션과 마찬가지로 body.transaction.id 로 멱등성을 보장하길 권장합니다.
분당 호출 횟수 제한 해제 필수
파트너 서버는 HighEnd 플랫폼의 반복 호출에 대응할 수 있어야 하므로, 반드시 분당 호출 횟수 제한을 설정하지 말아야 합니다.
구현이 어려운 경우
가장 간단한 구현 방식은 다음과 같습니다:
body.username으로 유저를 찾고항상
body.amount만큼 잔액을 increment 연산으로 조정합니다.body.transaction.id의 멱등성은 가능하면 보장하는 것이 좋습니다.body.amount의 부호는 HighEnd 플랫폼이 관리 합니다. 파트너는 increment 연산만 수행하면 됩니다.
기록 및 문의
HighEnd 플랫폼은 통신 과정에서 유실되거나 이상한 응답을 모두 기록합니다.
문제 발생 시, 백오피스 기록 확인 후 서비스 데스크로 문의 주세요.
Last updated