BITUP 파트너 API

심리스 월렛 연동 가이드

1. 개요

BITUP 파트너 API는 파트너 시스템과 BITUP 베팅 플랫폼 간의 원활한 연동을 지원합니다. 파트너는 회원 계정 관리, 베팅 처리, 정산을 안전한 콜백 기반 구조로 처리할 수 있습니다.

기본 URL

https://bet.bitupgo.com/api/partner.php

인증 방식

모든 요청에 X-Partner-Key 헤더가 필요합니다.

X-Partner-Key: 발급받은_시크릿_키

응답 형식

모든 응답은 JSON 형식이며 success 필드로 성공/실패를 구분합니다.

2. 파트너 API 엔드포인트

2.1 로그인 (SSO)

POST /api/partner.php?action=login

회원의 자동 로그인 URL을 생성합니다. 회원이 존재하지 않으면 자동으로 가입 처리됩니다.

요청 파라미터

파라미터타입필수설명
user_id문자열O회원 아이디
user_pw문자열O비밀번호
nickname문자열X닉네임 (미입력 시 user_id 사용)

응답 (성공)

{
  "success": true,
  "login_url": "https://bet.bitupgo.com/auth/token_login.php?token=abc123...",
  "expires_in": 60
}
토큰은 60초 후 만료됩니다. login_url로 회원을 리다이렉트하면 자동 로그인됩니다.

응답 (실패)

{
  "success": false,
  "error": "Invalid partner key | Missing user_id or user_pw | Invalid password"
}

2.2 잔액 조회

GET /api/partner.php?action=balance&user_id=xxx

파라미터타입필수설명
user_id문자열O회원 아이디

응답

{
  "success": true,
  "data": {
    "user_id": "username",
    "nickname": "닉네임",
    "balance": 500000.00
  }
}

2.3 베팅 결과 조회

GET /api/partner.php?action=result&tx_id=xxx

트랜잭션 ID로 베팅 결과를 조회합니다.

파라미터타입필수설명
tx_id문자열Odebit 콜백 시 전달된 트랜잭션 ID

응답

{
  "success": true,
  "data": {
    "tx_id": "tx_xxx",
    "user_id": "username",
    "game_id": "202601270001",
    "bet_type": "UP",
    "amount": 10000.00,
    "approved_amount": 10000.00,
    "win_amount": 19500.00,
    "profit": 9500.00,
    "result": "win",
    "start_price": 100000.50,
    "end_price": 101000.50,
    "round_result": "UP",
    "status": "approved",
    "created_at": "2026-01-27 12:34:56",
    "settled_at": "2026-01-27 12:35:30"
  }
}

2.4 베팅 이력 조회

GET /api/partner.php?action=history&user_id=xxx

파라미터타입필수설명
user_id문자열O회원 아이디
limit정수X페이지당 건수 (기본 20, 최대 100)
offset정수X페이지네이션 오프셋 (기본 0)

응답

{
  "success": true,
  "data": [
    {
      "tx_id": "tx_xxx",
      "bet_type": "UP",
      "amount": 10000.00,
      "win_amount": 19500.00,
      "result": "win",
      "game_id": "202601270001",
      "created_at": "2026-01-27 12:34:56"
    }
  ]
}

2.5 하부 파트너 생성

POST /api/partner.php?action=create_partner

파라미터타입필수설명
user_id문자열O아이디
user_pw문자열O비밀번호 (최소 4자)
nickname문자열X닉네임
commission_rate실수X커미션율 % (0 ~ 내 커미션율 이하)
prefix문자열O영문/숫자/_ 3~16자 (고유, 변경 불가)

응답

{
  "success": true,
  "partner": {
    "user_id": 123,
    "username": "PREFIX_username",
    "partner_code": "PREFIX_ABC123",
    "commission_rate": 2.0
  }
}
Prefix는 고유해야 하며, 한 번 설정 후 변경할 수 없습니다. 하부 회원의 아이디에 자동으로 Prefix가 붙습니다.

2.6 커미션 내역 조회

GET /api/partner.php?action=commission

파라미터타입필수설명
date_from문자열X시작일 Y-m-d (기본: 7일 전)
date_to문자열X종료일 Y-m-d (기본: 오늘)
game_type문자열X"30s" 또는 "60s"

응답

{
  "success": true,
  "summary": {
    "total_count": 150,
    "total_commission": 50000.00,
    "total_bet_amount": 1000000.00
  },
  "data": [
    {
      "round_number": 1234,
      "game_type": "30s",
      "bet_user": "username",
      "bet_amount": 10000.00,
      "commission_rate": 2.0,
      "commission_amount": 100.00,
      "created_at": "2026-04-15 12:34:56"
    }
  ]
}

3. 심리스 월렛 콜백

파트너가 심리스 월렛 모드를 활성화하면, BITUP은 모든 잔액 변동 시 파트너가 설정한 URL로 HTTP 콜백을 전송합니다.

콜백 인증

POST {파트너_콜백_URL}
Content-Type: application/json
X-Signature: HMAC-SHA256(요청_본문, callback_secret_key)
X-Partner-Id: {파트너_ID}
서명 검증 방법: 수신한 요청 본문(raw body)을 callback_secret_key로 HMAC-SHA256 해시하여 X-Signature 헤더 값과 비교합니다. 불일치 시 401로 거부하세요.

공통 응답 형식

// 성공
{ "success": true, "balance": 490000.00, "tx_id": "tx_xxx" }

// 실패
{ "success": false, "error": "잔액 부족" }

3.1 잔액 조회 콜백

POST {callback_balance_url}

BITUP → 파트너로 회원 잔액을 조회합니다.

요청

{
  "action": "balance",
  "user_id": "회원아이디",
  "timestamp": 1672531200
}

파트너 응답

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

3.2 차감 콜백 (베팅)

POST {callback_debit_url}

회원이 베팅하면 BITUP이 파트너에게 차감을 요청합니다.

요청

{
  "action": "debit",
  "user_id": "회원아이디",
  "game_id": "202601270001",
  "game_type": "30s",
  "amount": 10000.00,
  "tx_id": "tx_abc123",
  "timestamp": 1672531200
}

파트너 응답

{ "success": true, "balance": 490000.00, "tx_id": "tx_abc123" }
차감 실패(잔액 부족 등) 시 success:false를 반환하면 베팅이 자동 취소됩니다.

3.3 지급 콜백 (당첨금)

POST {callback_credit_url}

회원이 베팅에서 승리하면 당첨금을 지급합니다.

요청

{
  "action": "credit",
  "user_id": "회원아이디",
  "game_id": "202601270001",
  "game_type": "30s",
  "win_amount": 19500.00,
  "tx_id": "tx_abc123",
  "start_price": 100000.50,
  "end_price": 101000.50,
  "result": "UP",
  "timestamp": 1672531200
}

파트너 응답

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

3.4 취소 콜백 (환불)

POST {callback_cancel_url}

베팅이 취소/무효 처리되면 차감된 금액을 환불합니다.

요청

{
  "action": "cancel",
  "user_id": "회원아이디",
  "game_id": "202601270001",
  "amount": 10000.00,
  "tx_id": "tx_abc123",
  "void_reason": "라운드 취소",
  "timestamp": 1672531200
}

파트너 응답

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

4. 알(R) 시스템

파트너에게는 알(Egg) 잔액이 부여되며, 이는 베팅 한도이자 GGR 정산 원장 역할을 합니다.

알 변동 규칙

이벤트알 변동설명
회원 베팅-배팅금액파트너 알에서 차감
회원 당첨+당첨금액파트너 알에 복원 (본사가 지급)
회원 낙첨변동 없음이미 차감된 금액 = 파트너 수익
베팅 취소/무효+배팅금액파트너 알에 환불
파트너 알 잔액이 부족하면 회원의 베팅이 거부됩니다. 본사에서 알을 충전받아야 합니다.

알 관리

5. 베팅 흐름

5.1 베팅 접수

1. 회원이 UP 또는 DOWN 선택 후 베팅
2. 파트너 알 잔액 확인 (부족 시 거부)
3. 심리스 모드: 파트너에 debit 콜백 전송
4. 콜백 성공 시 베팅 확정, 실패 시 취소
5. 알(Egg) 차감 기록

5.2 정산

1. 라운드 종료 후 BTC 가격으로 승패 판정
2. 승리: credit 콜백 → 당첨금 지급 + 알 복원
3. 패배: 알 변동 없음 (이미 차감 확정)
4. 무효: cancel 콜백 → 배팅금 환불 + 알 복원

5.3 배당률

조건배당률설명
양쪽 매칭1.95배5% 수수료 차감 후 지급
한쪽만 베팅1.95배하우스가 상대방 역할

6. 게임 종류

타입라운드 시간배당률설명
30s30초1.95배BTC 가격 UP/DOWN 예측
60s60초1.95배BTC 가격 UP/DOWN 예측

7. 에러 코드

HTTP 코드설명
200성공 (본문의 success 필드로 상세 확인)
401인증 실패 (X-Partner-Key 누락 또는 불일치)
400잘못된 요청 (필수 파라미터 누락)
500서버 오류

8. 보안 권장사항

9. 콜백 설정

파트너 관리 페이지에서 다음 4개 URL을 설정합니다:

항목설명
callback_balance_url잔액 조회 URL
callback_debit_url베팅 차감 URL
callback_credit_url당첨금 지급 URL
callback_cancel_url베팅 취소/환불 URL
콜백 활성화 후 "테스트 전송" 버튼으로 정상 동작을 확인하세요.