Steam 소액결제 - InitTxn
기본 정보
- Steam 소액결제 프로세스 중 InitTxn을 랩핑해서 제공하는 빌링 API입니다.
- 빌링 시스템 예약 후 호출되어야 합니다.
- InitTxn API요청이 성공하면 Steam 게임 내 오버레이를 통해서 사용자에게 알림이 전송됩니다. API 요청에 포함된 아이템 설명을 바탕으로 거래 정보가 표시되고 유저는 거래를 승인할 수 있습니다.
- 스팀쪽 소액 결제 구현가이드를 읽어보고 이해도를 높이면 좋습니다.
- 스팀은 구글 또는 애플처럼 상품을 관리해주는 기능이 없습니다. 스팀에 입점하는 개발사가 자체 관리해야합니다.
- 전시 기능을 제외한 상품의 메타정보(상품의 기본 정보)는 빌링시스템에서 자체 관리해서 제공 해드립니다.(즉, 빌링 시스템에 상품 등록이 필요합니다.)
- 기본 설정은 SandBox 환경으로 셋팅되어 있습니다. 오픈 전이나 실 결제 테스트가 필요할 때 요청주시면 변경해드립니다.
| 항목 | 내용 | 비고 |
|---|---|---|
| 호출주체 | 게임서버(s2s API) | |
| 도메인 | 각 환경별 도메인 | |
| 인증 방식 | HTTP 헤더 인증 정보 | |
| HTTP 메소드 | POST | |
| Content-Type | application/json | |
| 사전 필요사항 |
|
Request
HTTP Request end point
POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/steam/microtxn/initTxn
HTTP Request Header
- 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
| 이름 | 값 | 비고 |
|---|---|---|
| X-Req-Pjid | 프로젝트ID | 기술 PM 등에게 전달받은 프로젝트ID |
| X-Auth-Access-Key | 인증용 키 | 기술 PM 등에게 전달받은 해당 게임용 인증 키 |
HTTP Request Parameter
- Content-Type: application/json 으로 요청되어야 합니다.
- 빌링 API에서 전달받은 파라미터는 Steam의 InitTxn web API를 호출할 때 사용 됩니다.
- 해당 Steam web API 정의서 내용의 주의사항을 읽어보시는게 도움이 됩니다.
| key(1 depth) | key(2 depth) | type | 설명 | 예 |
|---|---|---|---|---|
| reqId | String(100) | 중복 요청을 막거나 요청 추적을 위한 값 | userId_UUID 등과 같은 방식으로 생성 | |
| pjid | String(20) | 프로젝트ID
| 1004 | |
| boid | String(20) | 빌링 시스템 구매 예약 API를 통해서 생성된 ID
| 1234 | |
| steamId | long | Steam ID of user making purchase | ||
| steamLanguage | String | ko | ||
| steamCurrency | String |
| KRW |
HTTP Request Parameter(Sample json)
- 요청 샘플 json입니다. 하단 curl 커맨드를 참고하셔도 좋습니다.
{
"reqId":"userId_steam_initTx_170083bf-8d85-433f-8bd2-67674b7482db-2023-12-03-01",
"pjid":"9001",
"boid":"1",
"steamId":"76561198119773705",
"steamLanguage": "ko",
"steamCurrency":"KRW"
}
Response
응답은 JSON형태로 전달됩니다.
Success sample
- InItTxn이 성공하게되면 유저는 스팀내 인게임에서 오버레이로 아래와 같은 구매 창이 뜨게 되고 구매 프로세스를 진행할 수 있습니다.
{
"resultCode": "SUCCESS",
"resultMessage": "Success steam initTxn. Users will see a purchase window appear in-game on Steam."
}
IniTxn API 성공시 유저가 보게되는 스팀내의 구매 화면
- 클라이언트(스팀내 게임 앱) → 게임서버 → 빌링 API InitTxn → Steam Web API 호출이 성공하게되면 인게임내 유저는 아래와 같은 오버레이 구매 팝업창을 보게 됩니다.
-8d135f1d0ae8cdcaca23b1f8db66c63e.png)
Error sample
- 사용자가 로그인하지 않음으로 Steam web api에서 에러 코드 7 번이 리턴
- 디버깅에 참고하시도록 resultData에 Steam응답을 파싱하여 응답해드립니다.(스팀의 에러 코드 정의)
{
"resultCode": "STEAM_RESULT_FAILURE",
"resultMessage": "See Error Codes : https://partner.steamgames.com/doc/features/microtransactions/implementation#error_codes",
"resultData": {
"result": "Failure",
"params": {
"orderid": "17016144403",
"transid": null,
"steamurl": null
},
"error": {
"errorcode": "7",
"errordesc": "User 76561198119773705 not logged in"
}
}
}
- 이미 InitTxn이 진행된 boid(빌링주문ID)로 재 요청된 경우 에러 샘플
{
"resultCode": "INVALID_PARAMETER",
"resultMessage": "already initTxn 'boid: 1' in microTxn DB"
}
- Steam API 자체가 응답이 느려서 Timeout이 발생한 경우
{
"resultCode": "EXTERNAL_API_ERROR",
"resultMessage": "Steam API 'https://partner.steam-api.com/ISteamMicroTxnSandbox/InitTxn/v3/' timeout. Steam API Timeout error(10000ms)"
}
에러 코드 정의(resultCode부분)
- 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
- 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
- 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
- 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
| 에러코드 | 비고 |
|---|---|
| SYSTEM_ERROR | 빌링 API에서 발생한 시스템 에러
|
| NOT_ALLOW_AUTH | API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생 |
- 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
| 에러코드 | 비고 |
|---|---|
| INVALID_PARAMETER | |
구매 기능을 사용할 수 없는 상황
| |
| STEAM_RESULT_FAILURE | Steam web API 호출은 성공했지만, 결과가 실패로 리턴됨
|
| EXTERNAL_API_ERROR | Steam web API 호출 자체가 실패한 경유 |
요청 curl 샘플
- 도메인 및 인증 헤더 등은 변경 필요
curl --location 'http://localhost:10001/billing/api-game/v1/purchase/steam/microtxn/initTxn' \
--header 'X-Req-Pjid: 입력필요' \
--header 'X-Auth-Access-Key: 입력필요' \
--header 'Content-Type: application/json' \
--data '{
"reqId":"userId_steam_initTx_170083bf-8d85-433f-8bd2-67674b7482db-2023-12-03-01",
"pjid":"9001",
"boid":"1",
"steamId":"숫자포맷의 유저 스팀ID입력 필요",
"steamLanguage": "ko",
"steamCurrency":"KRW"
}'