Steam 소액결제 - QueryTxn
기본 정보
Steam 소액결제 유틸성 API로 사용 가능한 QueryTxn을 랩핑해서 제공하는 빌링 API입니다.
타임 아웃 등이 발생해서 재 요청을 위해서 현재 상태를 조회하는 등의 기능에서 사용 가능합니다.
InitTxn 성공 후 Steam에서 응답 받은 SteamTransId 기반으로 작동합니다.
boid로 빌링 DB에 저장해둔 SteamTransId와 SteamOrderId로 QueryTxn을 호출
호출주체
게임서버(s2s API)
HTTP 메소드
POST
Content-Type
application/x-www-form-urlencoded
사전 필요사항
프로젝트ID 및 서비스 ID 발급
Steam works 설정 후 빌링 시스템 설정
Request
HTTP Request end point
POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/steam/microtxn/queryTxnHTTP 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 으로 호출하면 됩니다.
reqId
String(100)
중복 요청을 막거나 요청 추적을 위한 값
userId_UUID 등과 같은 방식으로 생성
pjid
String(20)
프로젝트ID
동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음
1004
boid
String(20)
빌링 시스템 구매 예약 API를 통해서 생성된 ID
Steam 응답에 에러가 반환시 빌링 API 예약부터 다시 진행되어야할 수 있습니다.(실제 결제 테스트 후 확인 필요). 스팀 web API 요구사항 때문
1234
Response
응답은 JSON형태로 전달됩니다.
Response property
resultData 부분의 설명입니다.
아래 성공 샘플과 함께 참고하시면 됩니다.
Steam의 QueryTxn의 결과를 랩핑해서 일부 필드명만 변경해서 응답해드립니다.
상세 내용은 Steam QueryTxn 결과 필드를 참고하시는게 좋습니다.(링크)
steamOrderId
String
Unique 64-bit ID for order.
116
steamTransId
String
Unique 64-bit Steam transaction ID.
6797682191488555496
steamId
String
The Steam ID of user that the order/transaction belongs to.
76561198119773705
currency
String
ISO 4217 currency code.
KRW
time
String
Time of transaction (RFC 3339 UTC formatted like: 2010-01-01T00:00:00Z)
2023-11-16T01:19:44Z
country
String
ISO 3166-1-alpha-2 country code.
KR
usState
String
US State. Empty for non-US countries.
items
json array
qty
Integer
Quantity of this item.
1
amount
String
Total cost to user minus VAT (in cents). (199 = 1.99)
91000
vat
Double
Total VAT or tax (in cents). (19 = .19)
9000.0
itemid
String
Game ID number of item.
1001
itemstatus
String
Status 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_AUTH
API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
아래 에러 코드들은 해당 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'Last updated