search

One wallet API 연동 가이드

이 문서는 에이전트 측 서버가 반드시 구현해야 하는 Wallet API 명세입니다. META는 이 API를 호출하여 유저의 잔액을 조회하거나 변경합니다. 모든 요청은 안정성과 멱등성을 고려해 처리해야 하며, 다음 사항을 반드시 참고하세요.

hashtag
응답 규칙

  • success 필드는 반드시 포함되어야 하며, 요청 처리 결과에 따라 다음 필드를 추가해야 합니다:

    • success: true일 경우 → balance 필드 필수 → 처리된 후 또는 현재의 잔액을 의미합니다.

    • success: false일 경우 → error 필드 필수 → 처리 실패 또는 거부에 대한 명확한 에러 메세지를 포함해야 합니다.

  • ⚠️ 에러 발생 또는 에이전트가 내부 규정에 의해 처리를 거부하더라도, 다음 두 가지 상황에서 HTTP 응답 코드는 200 또는 201로 처리해야 합니다:

    • 요청 포맷이 올바르고 요청을 처리 가능하지만, 에이전트 측 도메인 로직 상 잔액 변경을 거부한 경우

    • 처리는 실패했지만, handling 가능한 에러로 판단된 경우

  • 위 경우, success: false와 함께 error를 포함하여 응답하면 됩니다.

  • 예시:

    • 처리 성공:

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

    • 처리 실패 (에러 메시지 포함):

      {
  "success": false,
  "error": "차단된 유저"
}

hashtag
멱등성 및 트랜잭션 처리

  • 요청 또는 응답은 언제든 유실될 수 있습니다.

  • body.transaction.id는 META의 트랜잭션 고유 ID이며, 멱등성 보장을 위해 사용됩니다.

  • 동일한 body.transaction.id가 다시 전달된 경우:

    • 이전 요청에 대한 처리가 성공했다면, 변경 없이 현재 잔액을 반환해야 합니다.

    • 이전 요청에 대한 처리가 실패했다면, 다시 시도 후 응답(성공/실패)을 반환해야 합니다.

hashtag
잔액 증감 처리 방식

  • body.amount는 양수, 0, 음수 모두 가능하며, 반드시 increment 연산으로 처리해야 합니다.

hashtag
트랜잭션 그룹화 기준

BET / WIN / CANCEL은 회원의 게임 플레이로 인해 발생한 트랜잭션입니다. 에이전트 측에서 회원의 게임 기록을 저장하고자 할 경우, 위 세 가지 타입의 트랜잭션을 기록해야 합니다. 게임기록은 body.transaction.context.round_id를 기준으로 그룹화할 수 있습니다. 동일한 round_id에 대해 BET / WIN / CANCEL 트랜잭션이 여러 번 발생할 수 있습니다.

hashtag
🟡 결과가 발생하지 않은, 대기 상태로 남아있는 트랜잭션 구별 방법

동일한 round_id에 대해 BET 트랜잭션만 존재하고, WIN, CANCEL 트랜잭션이 아무것도 없는 경우 해당 BET 트랜잭션은 아직 결과가 발생하지 않은 대기 상태의 트랜잭션입니다.

이와 같이 결과가 발생하지 않은 트랜잭션을 구별해야 하는 경우, 다음 조건을 확인하세요:

  • BET 트랜잭션이 존재함.

  • 위 BET 트랜잭션의 round_id와 동일한 round_id를 가진 WIN, CANCEL 트랜잭션이 아무것도 기록돼 있지 않음.

위 조건을 만족하는 트랜잭션은, 결과 미처리가 의심되는 상태입니다. 해당 트랜잭션을 발견했다면, 트랜잭션의 body.transaction.id 값과 함께 META 서비스 데스크로 문의 주세요.

참고로, body.transaction.previous_tx_id를 가진 트랜잭션은 해당 previous_tx_id와 일치하는 body.transaction.id를 가진 트랜잭션의 결과 트랜잭션을 의미합니다.

그러나 이 previous_tx_id를 기반으로 BET과 WIN를 참조하는 방식은 권장되지 않습니다, 이유는 다음과 같습니다:

  1. BET에 대한 WIN이 발생하지 않을 수 있으며, (Example: Pragmatic Play LIVE_CASINO 게임)

  2. 하나의 BET 트랜잭션에 여러 개의 WIN 트랜잭션이 대응할 수 있습니다. (Example: PgSoft SLOT 게임)

  • 위 두 가지 case는 게임사의 처리 방식에 따라 발생하며, 정상적인 상황입니다. 그러므로 반드시 round_id 로 판단해야 합니다.

⚠️ CANCEL 트랜잭션 처리 시 주의사항

CANCEL 트랜잭션은 BET트랜잭션을 취소하기 위한 트랜잭션 입니다.

CANCEL 트랜잭션의 body.transaction.id는 취소할 BET트랜잭션의 body.transaction.id 가 아닙니다.

META의 트랜잭션 고유 id 입니다. CANCEL 트랜잭션 또한 다른 트랜잭션과 마찬가지로 body.transaction.id 로 멱등성을 보장하길 권장합니다.

⚠️ 분당 호출 횟수 제한 해제 필수

  • •에이전트 서버는 META의 반복 호출에 대응할 수 있어야 하므로, 반드시 분당 호출 횟수 제한을 설정하지 말아야 합니다.

구현이 어려운 경우

가장 간단한 구현 방식은 다음과 같습니다:

  • •body.username으로 유저를 찾고

  • •항상 body.amount만큼 잔액을 increment 연산으로 조정합니다.

  • •body.transaction.id의 멱등성은 가능하면 보장하는 것이 좋습니다.

•body.amount의 부호는 META가 handling합니다. 에이전트는 increment 연산만 수행하면 됩니다.

기록 및 문의

  • •META는 통신 과정에서 유실되거나 이상한 응답을 모두 기록합니다.

  • •문제 발생 시, 백오피스 기록 확인 후 서비스 데스크로 문의 주세요.

Previous[GET] 게임 조회Next[GET] 유저 밸런스 조회

Last updated

Was this helpful?