본문으로 건너뛰기

Steam 소액결제 - QueryTxn

기본 정보​

  1. Steam 소액결제 유틸성 API로 사용 가능한 QueryTxn을 랩핑해서 제공하는 빌링 API입니다.
    1. 타임 아웃 등이 발생해서 재 요청을 위해서 현재 상태를 조회하는 등의 기능에서 사용 가능합니다.
  2. InitTxn 성공 후 Steam에서 응답 받은 SteamTransId 기반으로 작동합니다.
    1. boid로 빌링 DB에 저장해둔 SteamTransId와 SteamOrderId로 QueryTxn을 호출
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증 방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/x-www-form-urlencoded
사전 필요사항
  1. 프로젝트ID 및 서비스 ID 발급
  2. Steam works 설정 후 빌링 시스템 설정

Request​

HTTP Request end point​

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/steam/microtxn/queryTxn

HTTP Request Header​

  • 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
이름값비고
X-Req-Pjid프로젝트ID기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key인증용 키기술 PM 등에게 전달받은 해당 게임용 인증 키

HTTP Request Parameter​

  • 아래 파라미터들을 Content-Type: application/x-www-form-urlencoded 으로 호출하면 됩니다.
keytype설명예
reqIdString(100)중복 요청을 막거나 요청 추적을 위한 값userId_UUID 등과 같은 방식으로 생성
pjidString(20)

프로젝트ID

  • 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음
1004
boidString(20)

빌링 시스템 구매 예약 API를 통해서 생성된 ID

  • Steam 응답에 에러가 반환시 빌링 API 예약부터 다시 진행되어야할 수 있습니다.(실제 결제 테스트 후 확인 필요). 스팀 web API 요구사항 때문
1234

Response​

응답은 JSON형태로 전달됩니다.

Response property​

  • resultData 부분의 설명입니다.
  • 아래 성공 샘플과 함께 참고하시면 됩니다.
  • Steam의 QueryTxn의 결과를 랩핑해서 일부 필드명만 변경해서 응답해드립니다.
    • 상세 내용은 Steam QueryTxn 결과 필드를 참고하시는게 좋습니다.(링크)
key(1 depth)key(2 depth)data typedescriptionexample
steamOrderId StringUnique 64-bit ID for order.116
steamTransId StringUnique 64-bit Steam transaction ID.6797682191488555496
steamId StringThe Steam ID of user that the order/transaction belongs to.76561198119773705
status String

Status of the order. (참고 링크)

  • 주의: 빌링의 구매 상태코드가 아닙니다.
currency StringISO 4217 currency code.KRW
time StringTime of transaction (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z)2023-11-16T01:19:44Z
country StringISO 3166-1-alpha-2 country code.KR
usState StringUS State. Empty for non-US countries.
items json array
qtyIntegerQuantity of this item.1
amountStringTotal cost to user minus VAT (in cents). (199 = 1.99)91000
vatDoubleTotal VAT or tax (in cents). (19 = .19)9000.0
itemidStringGame ID number of item.1001
itemstatusStringStatus of items within the order.Failed

Success sample​

  • FinilizeTxn까지 최종 완료된 경우
{
    "resultCode": "SUCCESS",
    "resultMessage": "request success",
    "resultData": {
        "steamOrderId": "17015949805",
        "steamTransId": "3680066791721636308",
        "steamId": "76561198119773705",
        "status": "Succeeded",
        "currency": "KRW",
        "time": "2023-12-03T09:19:00Z",
        "country": "KR",
        "usState": "",
        "items": [
            {
                "qty": 1,
                "amount": "900000",
                "vat": "90000",
                "itemid": "75",
                "itemstatus": "Succeeded"
            }
        ]
    }
}
  • 유저가 구매 승인까지 완료한 경우(InitTxn 후 구매 창에서 승인 완료했지만 아직 FinlizeTxn 호출 안됨)
{
    "resultCode": "SUCCESS",
    "resultMessage": "request success",
    "resultData": {
        "steamOrderId": "17015949805",
        "steamTransId": "3680066791721636308",
        "steamId": "76561198119773705",
        "status": "Approved",
        "currency": "KRW",
        "time": "2023-12-03T09:16:27Z",
        "country": "KR",
        "usState": "",
        "items": [
            {
                "qty": 1,
                "amount": "900000",
                "vat": "90000",
                "itemid": "75",
                "itemstatus": "Approved"
            }
        ]
    }
}

Error sample​

  • 잘못된 boid로 요청
{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "There is no purchase data that matches your criteria(boid '51')."
}

에러 코드 정의(resultCode부분)​

  • 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
  • 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
    • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
    • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
에러코드비고
SYSTEM_ERROR

빌링 API에서 발생한 시스템 에러

  • HTTP 상태코드 500 리턴
NOT_ALLOW_AUTHAPI 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
  • 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
에러코드비고
INVALID_PARAMETER
EXTERNAL_API_ERROR

Steam web API 호출 자체가 실패한 경우

  • 타임아웃 발생 등의 사유로 실패

요청 curl 샘플​

  • 도메인 및 인증 헤더 등은 변경 필요
curl --location 'https://billing-game-api-dev-public.pub-dev.hybegames.io/billing/api-game/v1/purchase/steam/microtxn/queryTxn' \
--header 'X-Req-Pjid: 9001' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reqId=userId_finalizeTxn_170083bf-8d85-433f-8bd2-67674b7482db-2023-12-03-01' \
--data-urlencode 'pjid=9001' \
--data-urlencode 'boid=78'