Seamless Wallet 개요

Ruby는 브랜드를 위해 Seamless와 Transfer 두 가지 지갑(Wallet) 연동 모드를 지원합니다. 이 페이지에서는 두 모드의 차이점을 설명하고 귀사의 플랫폼에 적합한 모드를 선택하는 데 도움을 드립니다.

지갑 모드

Transfer 모드

Transfer 모드에서는 Ruby가 각 플레이어에 대한 내부 선불 지갑을 관리합니다. 플레이어가 게임 세션을 시작하면 귀사의 브랜드 지갑에서 Ruby의 내부 시스템으로 자금이 이체됩니다. 승패 정산은 Ruby의 지갑 내에서 처리되며, 잔액은 주기적으로 정산합니다.

특징:

귀사 측에 콜백(Callback) 엔드포인트가 필요하지 않습니다
간단한 연동 -- 서버 측 구현이 불필요합니다
잔액은 Ruby가 관리하며, 귀사의 플랫폼은 Ruby에 현재 잔액을 조회합니다
저복잡도 연동을 원하거나 선불 크레딧 모델을 운영하는 운영자에게 적합합니다

Seamless 모드

Seamless 모드에서는 Ruby가 내부 플레이어 지갑을 유지하지 않습니다. 대신, 잔액에 영향을 미치는 모든 게임 이벤트가 실시간 HTTP 콜백을 통해 귀사의 서버로 전송됩니다. 귀사 플랫폼의 지갑이 항상 플레이어 자금의 단일 원본(Single Source of Truth)으로 유지됩니다.

특징:

모든 게임 이벤트(베팅, 당첨, 롤백)에 대한 실시간 콜백
귀사의 서버에 4개의 콜백 엔드포인트를 구현해야 합니다 (콜백 명세 참조)
플레이어 잔액이 항상 실시간으로 반영됩니다 -- 정산 지연이 없습니다
자체 지갑 시스템을 완전히 제어하고 실시간 잔액 가시성을 원하는 운영자에게 적합합니다

모드 선택

고려사항	Transfer	Seamless
연동 복잡도	낮음	중간
지갑 소유권	Ruby	귀사 플랫폼
실시간 잔액	아니오 (주기적 동기화)	예
콜백 엔드포인트 필요 여부	아니오	예
가동 시간 의존성	낮음	높음 -- 귀사의 콜백 서버가 항상 가용해야 합니다
적합 대상	간단하거나 선불 방식의 연동	기존 지갑 인프라를 보유한 운영자

귀사의 플랫폼이 이미 플레이어 잔액을 관리하고 있으며 실시간 자금 정확성을 원하신다면 Seamless를 선택하십시오. 서버 측 콜백 요구사항 없이 가벼운 연동을 선호하신다면 Transfer를 선택하십시오.

Seamless 모드 작동 방식

다음 시퀀스는 Seamless 모드에서 일반적인 게임 라운드 중 발생하는 과정을 설명합니다:

Player action (e.g., place a bet)
        │
        ▼
  Game Provider Server
        │
        │  Game event (bet/win/void)
        ▼
  Ruby Platform
        │
        │  POST {callback_url}/debit   ← Ruby calls your server
        ▼
  Your Wallet Server
        │
        │  { balance, balance_before }
        ▼
  Ruby Platform
        │
        │  Returns result to game provider
        ▼
  Game Provider Server

단계별 설명:

플레이어가 게임에서 액션을 수행합니다 (베팅, 당첨, 또는 라운드 무효화).
게임 제공사가 해당 이벤트를 Ruby 플랫폼으로 전송합니다.
Ruby는 이벤트를 지갑 콜백으로 변환하여 귀사의 callback_url에 있는 해당 엔드포인트를 호출합니다:
- 베팅(Bet) -> POST {callback_url}/debit (플레이어 지갑에서 자금 차감)
- 당첨/정산(Win/Settlement) -> POST {callback_url}/credit (플레이어 지갑에 자금 추가)
- 무효/롤백(Void/Rollback) -> POST {callback_url}/rollback (이전 차감 취소)
- 잔액 조회(Balance query) -> POST {callback_url}/balance (상태 비저장 읽기, 자금 이동 없음)
귀사의 서버가 요청을 처리하고 지갑을 업데이트한 후 새로운 잔액을 반환합니다.
Ruby는 반환된 잔액을 사용하여 게임 제공사 흐름을 완료합니다.

모든 4개의 콜백은 HMAC-SHA256 서명으로 인증됩니다. 검증 세부사항은 콜백 인증을 참조하십시오.

Seamless 연동 요구사항

Seamless 모드로 본 서비스를 시작하기 전에 구현이 다음 요구사항을 충족하는지 확인하십시오:

엔드포인트 가용성

4개의 콜백 엔드포인트를 모두 구현해야 합니다: /balance, /debit, /credit, /rollback
귀사의 콜백 서버는 Ruby 서버에서 HTTPS를 통해 접근 가능해야 합니다
callback_url에는 후행 슬래시가 없어야 합니다 (예: https://wallet.example.com/ruby/가 아닌 https://wallet.example.com/ruby)

성능

하드 타임아웃: Ruby는 5초 이내에 응답하지 않는 콜백을 중단합니다
권장 응답 시간: 하드 타임아웃 이전의 여유를 확보하기 위해 3초 이내
느린 응답은 플레이어에게 게임 오류를 유발합니다 -- 콜백 지연 시간(Latency)을 핵심 지표로 취급하십시오

멱등성(Idempotency)

/debit, /credit, /rollback 엔드포인트는 반드시 멱등성을 보장해야 합니다
transaction_id를 사용하여 중복 요청을 감지하고, 재처리 없이 원래의 결과를 반환하십시오
/balance 엔드포인트는 상태 비저장 읽기이므로 멱등성 처리가 필요하지 않습니다

서명 검증

모든 수신 콜백 요청에서 X-Aggregator-Signature 헤더를 검증하십시오
유효하지 않은 서명, 만료된 타임스탬프, 또는 알 수 없는 API 키를 가진 요청은 거부하십시오
전체 검증 알고리즘은 콜백 인증을 참조하십시오

오류 처리

트랜잭션을 처리할 수 없는 경우 (예: 잔액 부족, 플레이어 미발견) 비-2xx HTTP 상태 코드를 반환하십시오
Ruby는 모든 2xx 상태를 성공으로 처리합니다. 비-2xx 응답은 게임 제공사에 오류로 전파됩니다
현재 자동 재시도 메커니즘은 없습니다 -- 실패한 콜백은 즉시 오류로 처리됩니다

다음 단계

콜백 명세 -- 4개 엔드포인트의 완전한 요청 및 응답 스키마
콜백 인증 -- 코드 예제가 포함된 서명 검증 가이드
테스트 -- 테스트 체크리스트 및 디버깅 가이드

지갑 모드​

Transfer 모드​

Seamless 모드​

모드 선택​

Seamless 모드 작동 방식​

Seamless 연동 요구사항​

엔드포인트 가용성​

성능​

멱등성(Idempotency)​

서명 검증​

오류 처리​

다음 단계​