빌링 상품 지급 API 제작 가이드

웹 상점 및 3자 결제 등에서 사용

해당 문서는 가이드이고 이후 추가 요청된 요구 사항 등을 감안해서 API 가이드를 작성 해 주셔야 합니다.

빌링 상품 지급 API는 결제/청약철회/아이템지급 방식 등의 결정 이후 제작 합니다.

기본정보

• MyCard 및 XSOLLA와 같은 결제 수단은 게임에서 상품 지급 주체가 될 수 없습니다.

• 빌링 시스템이 대신하여 유저 결제가 성공했을 때 게임쪽에 상품 지급 요청을 진행해드립니다.

  • 예) MyCard 웹샵 에서 유저 구매가 성공 → 빌링 시스템에서 게임쪽에 상품 지급 요청 API를 호출

• 상품 지급 요청 API를 아래 규약으로 개발 후 전달해주시면 빌링 시스템에 셋팅 후 이용할 수 있습니다.

• 인증 방식

  • 기본 사설 IP 기반으로 보안처리 되지만 필요 시 인증 헤더를 정의해서 제공해주시면 더 좋습니다.(필요시 논의 후 진행)

Request

HTTP Request end point에 대한 가이드

• /api/billing/give/product/payment_21315 형태의 API URL을 정의

  • 특정 고정된 랜덤 스트링은 혹시 모르는 보안 사고를 막기 위해서 임의로 정해서 사용 추천

  • 해당 url 포맷은 예제이고 어떤 url 포맷이어도 상관 없습니다.

POST https://각 환경별 게임서버 도메인/api/billing/give/product/{특정한 고정된 랜덤 스트링}

요청에 대한 추가 인증 및 보안

• 파라메터와 요청 서버에 대한 검증을 수행 할 수 있는 검증 코드나 검증 로직이 추가 되어야 합니다. 요청에 대해서 시크릿 키 등을 이용한 추가 인증을 진행할지 여부가 논의 후 추가될 수 있습니다.

HTTP Request Parameter

• Content-Type: application/json 으로 요청됩니다.

key(1 depth)	key(2 depth)	type	required	설명	예
pjid		String(20)	Y	프로젝트ID	1004
boid		String(20)	Y	빌링 주문ID
serverId		String(20)	N	지급대상 게임서버 ID	ASIA_SERVER, 10040100 등
serviceId		String(20)	N	지급대상 게임서버 serviceId	10040100
payment		String(20)	Y	결제가 진행된 스토어 또는 서비스	XSOLLA, MYCARD 등
appStore		String(20)	Y	구매가 이뤄지는 상점 스토어
os		String(10)	Y	구매한 디바이스의 OS 종류
imid		String	N	IMID
giveUser		json object	Y	상품을 지급해야하는 유저정보 데이터
	idType	String(10)	Y	ID종류	IMID, GAME_UID
	idValue	String(50)	Y	ID의 값
giveProductList		json array list		지급해야하는 상품 리스트
	productId	String		상품ID	xsolla_test_group_item_01
	quantity	Int		지급 상품 개수	1
	currency	String		구매 금액의 통화	USD
	totalMicroPrice	Long		구매 금액 micro단위

<key 상세 설명>

• pjid: 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같습니다.

• boid

  • 주의: 게임서버에서는 해당 값을 기준으로 중복지급 방지 처리 필수 구현 하셔야 합니다.

    • 게임 서버간 통신 중에 API응답 지연 등으로 재 처리 요청될 수 있습니다.

    • 게임쪽에서는 boid 기준으로 유니크 인덱스 생성등을 통한 방어를 추천합니다.

• serverId: 게임서버를 구분하지 않는 게임의 경우 null 일 수 있음

• serviceId: IM Assemble의 serviceId를 게임서버 ID 그대로 사용하는 경우를 위해서 제공 합니다.

• payment: 결제가 진행된 스토어 또는 서비스(돈을 지급한 행위가 발생한 스토어)로 게임쪽에서는 참고 정보로 활용 됩니다.

• appStore: 구매가 이뤄지는 상점 스토어(개발사 입장에서는 배포한 스토어)

  • 주의: CODA_SHOP 등 일반적으로 생각하는 앱 스토어가 아닌 개념 존재하고 paymentCd와 appStore값이 서로 틀릴 수도 있음

  • 현재 아래와 같은 코드를 사용 중이며 추가될 수 있음

    • GOOGLE_PLAY

    • GOOGLE_PLAY_PC

    • APPLE_APP_STORE

    • STEAM

    • IM_LAUNCHER

    • MYCARD

    • CODA_SHOP

    • UNIPIN

    • XSOLLA_WEBSHOP

    • GALAXY_STORE(예정)

    • ONE_STORE(예정)

    • DMM(예정)

• os: 구매한 디바이스의 OS 종류

  • 주의: 외부 결제 등 OS를 알 수 없는 경우 NONE일 수 있음

• imid: idType이 IMID인 경우에만 추가되는 IMID의 idVlaue

  • 특정 게임의 요청으로 개발된 예외 기능

• giveUser

  • idType

    • 여러 형태의 ID종류를 지원하기 위해서 type으로 구분하고 있습니다. (일반적으로 IMID를 기본으로 합니다.)

      • IMID: HYBE IM의 id로 플랫폼 로그인 후 얻게되는 id, 정책상 기본적으로 인게임에서 유저가 보게되는 id value의 종류

      • GAME_UID: 게임쪽에서 자체 정의한 유저ID

• idValue: 게임에서는 해당 유저 id에게 상품을 지급

• giveProductList: 현재 1개의 상품만 판매하는 형태로 사용 중이지만 특정 결제 수단에서 여러 건의 상품 구매 기능이 존재해서 확장성을 위해서 리스트 형태로 준비 되었습니다.

  • productId: 상품ID

  • quantity: 지급 상품 개수

  • currency: 구매 금액의 통화

  • totalMicroPrice: 구매 금액 micro단위 (해당 상품의 금액과 quantity값을 고려해서 합산)

    • 사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용

요청 샘플

{
   "pjid":"1201",
   "boid":"320",
   "serverId":"12010000",
   "serviceId":"12010000",
   "paymentCd":"CODA_SHOP",
   "payment":"CODA_SHOP",
   "appStore":"CODA_SHOP",
   "os":"NONE",
   "imid":"PUM4F8WJYJKJM3KHHHZS",
   "giveUser":{
      "idType":"IMID",
      "idValue":"PUM4F8WJYJKJM3KHHHZS"
   },
   "giveProductList":[
      {
         "productId":"codashop_test_1",
         "quantity":1,
         "totalMicroPrice":2000000,
         "currency":"USD"
      }
   ]
}

Response

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

Response property

• 지급 성공일 때는 resultCode에 SUCCESS로 입력 후 아래 추가 데이터를 resultData 필드에 추가해서 응답

key	data type	NotNull	description	example
giveCompletedAtUnixTS	Long	N (null 가능)	요청된 상품지급이 완료된 일시의 Unix Timestamp	null 또는 1704872037
playerId	String(50)	Y	실제 상품을 지급받은 playerId

<key 상세 설명>

• giveCompletedAtUnixTS: 요청된 상품지급이 완료된 일시의 Unix Timestamp

  • 게임쪽에서 유저가 접속 후 상품을 지급 받는 경우가 존재하여 nullable

    • 예) 엑솔라 외부 브라우저에서 유저는 구매 → 게임을 중지 → 유저는 오프라인 상태 → 게임서버에 지급 요청됨 → 유저는 재 로그인 후 상품을 지급 받기 때문에 지급 완료일시 정보가 없을 수 있음

  • 게임쪽에서 일반적으로 사용이 편하신 Unix Timestamp로 전달을 추천 합니다.

  • 빌링 시스템에서 UTC 0 타임존으로 파싱해서 사용합니다.

  • 실제 게임에서 지급된 시간이 최소 오차로 필요하기에 응답 받아야합니다. (예. 월 변경이 발생했을 때 한도제한 로직)

• playerId: 실제 상품을 지급받은 playerId

  • 지급 API 호출은 imid로 요청되기 때문에 실제 상품을 지급받은 게임쪽의 playerId 응답이 필요합니다.

  • 게임의 유저 스콥에 따라서 imid값이 될 수도 있습니다.

Success sample

application/json;charset=UTF-8
{
    "resultCode": "SUCCESS",
    "resultMessage": "request success",
    "resultData": {
        "giveCompletedAtUnixTS": 1704872037, 
	"playerId" : "abcdef"
    }
}

Error Sample

• 지급 실패인 경우 HTTP 상태 코드는 200이지만 resultCode에 정의된 에러코드와 함께 참고할 수 있는 메시지를 resultMessage로 응답해주시면 됩니다.

• 게임쪽에서는 HTTP 상태 코드 관리에 어려운 경우가 많으셔서 상태코드는 200으로 처리해주시면 됩니다

{ 
	"resultCode": "INVALID_USER", 
	"resultMessage": "not exist userId."
}

• 중복 지급 요청으로 에러인 경우 → ALREADY_GIVED_PRODUCT와 함께 이전에 지급했던 정보를 응답

{ 
	"resultCode": "ALREADY_GIVED_PRODUCT", 
	"resultMessage": "already gived product 'xsolla_product_01'. boid: '12'", 
	"resultData": { 
		"giveCompletedAtUnixTS": 1704872037,
		"playerId" : "abcdef"
	}
}

Error인 경우의 에러 코드 정의

• 아래의 에러 코드는 필수로 생각되는 에러 코드이며 추가되어야 할 에러코드가 있다면 공유 후 추가 가능

에러코드	비고
INVALID_PARAMETER	잘못된 파라미터로 API요청 시스템에서의 요청 파라미터가 잘못된 경우
INVALID_USER	잘못된 게임 유저 - 지급 해야 할 유저ID가 게임 내에 존재하지 않거나 제재 중인 경우 등 valid하지 않은 유저에게 상품 지급이 요청된 경우 에러코드 - 참고할 수 있는 상세 내용은 resultMessage에 전달해주시면 운영/디버깅에 좋습니다.
NOT_ALLOW_AUTH	API 사용 권한이 없는 경우 - 인증 정보가 잘못된 등 API 사용할 수 없는 요청인 경우
ALREADY_GIVED_PRODUCT	이미 지급 완료된 구매 건에 대해서 재 지급 요청 boid 기준으로 지급 여부를 판단하시면 됩니다. 상품 지급하기 전에 boid로 꼭 중복 지급 여부를 체크하시기 바랍니다.(boid로 유니크 인덱스를 설정하실 수 있다면 추천) 게임쪽 타임아웃 등의 이유로 빌링 시스템에서는 재 요청이 실행 될 수 있습니다. 이 때 게임에서는 해당 에러 코드로 리턴하고 resultData의 giveCompletedAtUnixTS 필드에 지급되었던 일시를 추가해주시면 됩니다.