Steam 소액결제 - InitTxn

기본 정보

Steam 소액결제 프로세스 중 InitTxn을 랩핑해서 제공하는 빌링 API입니다.
빌링 시스템 예약 후 호출되어야 합니다.
InitTxn API요청이 성공하면 Steam 게임 내 오버레이를 통해서 사용자에게 알림이 전송됩니다. API 요청에 포함된 아이템 설명을 바탕으로 거래 정보가 표시되고 유저는 거래를 승인할 수 있습니다.
1. 스팀쪽 소액 결제 구현가이드를 읽어보고 이해도를 높이면 좋습니다.
스팀은 구글 또는 애플처럼 상품을 관리해주는 기능이 없습니다. 스팀에 입점하는 개발사가 자체 관리해야합니다.
1. 전시 기능을 제외한 상품의 메타정보(상품의 기본 정보)는 빌링시스템에서 자체 관리해서 제공 해드립니다.(즉, 빌링 시스템에 상품 등록이 필요합니다.)
기본 설정은 SandBox 환경으로 셋팅되어 있습니다. 오픈 전이나 실 결제 테스트가 필요할 때 요청주시면 변경해드립니다.

항목

내용

비고

호출주체

게임서버(s2s API)

도메인

각 환경별 도메인

인증 방식

HTTP 헤더 인증 정보

HTTP 메소드

POST

Content-Type

application/json

사전 필요사항

프로젝트ID 및 서비스 ID 발급
Steamworks에 앱 등록 및 셋팅 후 빌링 시스템에 등록
빌링 시스템에 상품 등록 필요 다국어 대응된 상품명 국제화 처리된 가격 등

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

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

1004

boid

String(20)

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

참고: 스팀 web API 요구사항 때문에 Steam 응답에 에러가 반환되면 빌링 API 예약부터 다시 진행되어야합니다.

1234

steamId

long

Steam ID of user making purchase

스팀에서 구매를 진행하는 유저입니다. 추후 CS 대응 등에 중요하게 사용되기 때문에 정확히 전달 필요
- 참고: 본인의 Seam ID는 Steam웹 → 계정정보에서 확인 가능합니다.(링크)
클라이언트에서는 링크 글을 참고해서 얻을 수 있음

steamLanguage

String

ISO 639-1 language code of the item descriptions. Only works with the 28 fully supported Steam languages. (참고 링크)
1. 클라에서는 링크 글을 참고해서 얻을 수 있음
빌링 시스템에 해당 언어로 등록된 상품명이 없다면 영어 로 작동 됨

steamCurrency

String

ISO 4217 currency code
1. See Supported Currencies for proper format of each currency. (참고 링크)
빌링 시스템에 해당 통화로 상품이 등록이 안되어 있다면, 예약 때 요청된 productId의 ‘USD’로 요청
1. 빌링 시스템에 상품 등록시 해당 상품의 USD 가격은 필수로 입력되어야 합니다.

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 호출이 성공하게되면 인게임내 유저는 아래와 같은 오버레이 구매 팝업창을 보게 됩니다.

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에서 발생한 시스템 에러

HTTP 상태코드 500 리턴

NOT_ALLOW_AUTH

API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.

에러코드

비고

INVALID_PARAMETER

~~NOT_ALLOW_PURCHASE~~

구매 기능을 사용할 수 없는 상황

빌링 시스템에 스토어 관련 설정 누락
허용되지 않는 구매 요청 등

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"
}'

PreviousSteam 소액 결제 - 빌링 시스템에 구매 예약 NextSteam 소액결제 - FinalizeTxn

Last updated 9 months ago