Steam 소액결제 - QueryTxn

기본 정보

1. Steam 소액결제 유틸성 API로 사용 가능한 QueryTxn을 랩핑해서 제공하는 빌링 API입니다.

   1. 타임 아웃 등이 발생해서 재 요청을 위해서 현재 상태를 조회하는 등의 기능에서 사용 가능합니다.

2. InitTxn 성공 후 Steam에서 응답 받은 SteamTransId 기반으로 작동합니다.

   1. boid로 빌링 DB에 저장해둔 SteamTransId와 SteamOrderId로 QueryTxn을 호출

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증 방식	HTTP 헤더 인증 정보
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/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 으로 호출하면 됩니다.

key	type	설명	예
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 결과 필드를 참고하시는게 좋습니다.(링크)

key(1 depth)	key(2 depth)	data type	description	example
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
status		String	Status of the order. (참고 링크) 주의: 빌링의 구매 상태코드가 아닙니다.
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'