Skip to content

IAP Reference Server API

Jump to bottom
flyljj edited this page May 11, 2018 · 14 revisions

< 참고 >

본 문서는 원스토어 인앱 SDK v16(API v4)에 대한 가이드 문서입니다. 최신 원스토어 인앱 SDK v17(API v5)에 대한 가이드 문서는 원스토어 개발자센터에서 제공되고 있습니다.

최신 인앱 SDK v17 가이드 문서 링크 : https://dev.onestore.co.kr/devpoc/reference/view/IAP_v17

Server API

원스토어는 사용자가 정당하게 해당 Item을 구매했는지에 대한 여부를 조회할 수 있는 서버 API를 2가지 형태로 제공한다.

TID 구매이력 조회 API

구매 요청 시점에 개발사가 발급한 TID를 활용해서 사용자의 인앱상품 구매 이력을 조회하기 위한 API 이다.

전자영수증 검증 API

구매 완료 시점에 원스토어가 발급한 TxID와 receipt 을 활용해서 검증 Server를 통해 실제 IAP Server에서 발급된 것인지를 검증하고 동시에 구매 이력이 존재하는지 확인 가능하다. (SDK에서도 제공하는 기능이지만, 개발사 서버가 별도로 존재할 경우 Server to Server 호출을 권장한다)


TID 구매이력 조회 API

구매요청(sendPaymentRequest)시 개발사가 생성해서 넘겨주는 TID 를 key로 구매내역을 조회한다.

API 연동 흐름

alt text

주의 사항

  • App 서버를 운영하지 않는 경우, 전자영수증 검증 API를 이용하는 것을 권장한다.
  • 개발사는 TID 값을 유니크 값으로 관리해야 한다.
  • 만약 중복된 TID로 구매 요청을 하는 경우, 맨 마지막에 요청된 request에 해당 TID가 할당되며 이전 구매한 내역은 조회가 불가능하다.

TID 구매이력 조회 Request

요청URI

구분 URI
상용 http://iap.tstore.co.kr:8090/billIntf/billinglog/billloginquiry.action
개발 http://iapdev.tstore.co.kr:8082/billIntf/billinglog/billloginquiry.action

Reference

Parameter Limit sample Description
DATE 8 20101130 상품구매 일자
APPID 10 OA00012345 Application ID
TIDCNT 2 20 결제정보 확인을 위한 TID 개수, 최대 20건까지 조회가능
TID 100 `TIDCNT=2&TID=12313 12324`

TID는 TIDCNT 개수에 맞춰 최대 20개까지 요청이 가능하며, ‘|’ 로 구분한다.

Sample

  • Example: 개발용 IAP Server로 요청
http://iapdev.tstore.co.kr:8082/billIntf/billinglog/billloginquiry.action?DATE=20160715&APPID=OA00027256&TIDCNT=2&TID=12313|12324
  • Example: 상용 IAP Server로 요청
http://iap.tstore.co.kr:8090/billIntf/billinglog/billloginquiry.action?DATE=20160715&APPID=OA00027256&TIDCNT=2&TID=12313|12324

TID 구매이력 조회 Response

Reference

Parameter Limit sample Description
type BillingLog 요청 구분자 "BillingLog" 값으로 고정
result - 결제정보 그룹 Tag
status 4 <status>0</status> 결제정보 조회결과 코드
detail 4 <detail>0000</detail> 결제정보 조회결과 상세코드
message - <message>정상적으로 조회됐습니다.</message> 결제정보 조회결과 메시지
appid 10 <appid>OA00027256</appid> AID
count 2 <count>20</count> 확인된 결제정보 개수
billing_log - <billing_log>
<item>... </item>
</billing_log> 		IAP Server 에서 확인한 개별 결제 이력 정보의 모음으로 복수의 <Item> element 를 포함
Item - <item>
<tid>...</tid>
<product_id>...</product_id>
</item> 		Billing log 로 제공되는 개별 결제 항목으로 세부 결제 내역의 설명을 위해 아래와 같은 하위 element 를 포함
tid 100 <tid>201012226_01047637315_00000239</tid> TID
product_id 10 <product_id>0000044056</product_id> 인앱상품ID
log_time 10 <log_time>20101227103643</log_time> 상품 구매시각
charging_id 11 <charging_id>11111111111</charging_id > 결제성공 코드 (고정값)
charge_amount 7 <charge_amount>300000</charge_amount> 상품금액
detail_pname 100 <detail_pname>커스텀 상품명</detail_pname> 구매요청시 필요한 상세 상품명(product_name)을 입력했을 경우 리턴되는 값
선택 입력된 값이 없을 때는 ‘X’ 가 설정됨
bp_info 1024 utm_source=onestore&utm_medium=iap&utm_campaign=20160325_promotion 개발자의 Application Server 가 확인하기 위한 정보
tcash_flag 1 <tcash_flag>N</tcash_flag> T store Cash 사용 여부

Status

Code Description
0 성공
9 조회결과가 없거나 파라미터 및 시스템 오류

Detail

Code Description
0000 성공
1000 필수 파라미터 오류
2000 정의되지 않은 요청
3000 요청개수 오류
9100 결제정보 조회결과 없음
9200 요청개수 최대값(20) 초과
9999 시스템 오류

전자 영수증 검증 API

인앱 상품에 대한 구매 완료 후 발급되는 전자 영수증(receipt)의 검증을 수행할 수 있는 API로 SDK를 통해서 App2Server로 요청/응답을 받을 수 있다. 전자 영수증 검증은 구매 완료 후 10분 이내의 내역만 조회 가능하며 현재는 단일 조회만 가능하다.

API 연동 흐름

Built-in Model

서버없이 동작하는 Built-in Model의 경우, App내에서 IAP Library를 통해 결제 완료 통보를 받게 되는데, Application에서는 본 연동 흐름을 통해 아이템 발급(권한 부여 등) 처리 전에 실제 IAP Server를 통해 해당 상품에 대한 결제가 정상적으로 완료되었는지를 확인할 수 있다.

alt text

실선: 필수

점선: 선택

Server to Server

서버 연동형 상품의 경우, App 서버에서 IAP 서버와 연동을 통하여 발급된 전자 영수증 검증 요청하도록 제공하는 기능이다. 아래 시나리오는 예시이며, App의 서비스 시나리오에 따라 적절히 구현될 수 있다.

alt text

실선: 필수

점선: 선택


전자영수증 검증 Request

요청 데이터는 JSON 형식을 가지며 상세 규격은 다음과 같다.

요청URI

구분 URI
상용 https://iap.tstore.co.kr/digitalsignconfirm.iap
개발 https://iapdev.tstore.co.kr/digitalsignconfirm.iap

Reference

Parameter Type Mandatory Limit sample Description
txid String M 40 TSTOREXXXX_20150515102510XXXXXXXXXXXXXXX 영수증 번호
appid String M 10 OA00012345 AID
signdata String M ~5kb - 전자영수증 데이터

Sample

{
	"txid":"TSTORE0004_20150515102510XXXXXXXXXXXXXXX",
	"appid":"OA00012345",
	"signdata":"MIIH7QYJKoZIhvcNAQcCoIIH3jCCB9oCAQExDzANBglghkgBZQMEAMIIH7QYJKdDFDFFEFEFEFoZIhvcNAQcCoIIH3jCCB9oCAQExDzANBglghkgBZQMEA" 
}

전자영수증 검증 Response

IAP 서버는 요청 프로토콜내에 포함된 전자 영수증에 대한 검증 수행 후 결과값을 JSON 데이터 로 생성하여 요청자에게 전달한다.

Reference

Parameter Type Mandatory Limit sample Description
status Number M 1 0 검증 결과 리턴 코드
detail String M 4 0000 검증 결과 상세 코드
message String M - 정상검증완료 검증 결과 메시지
count Number O 1 1 조회 상품 수, 현재는 1건씩만 조회가능
product Array O - - 구매된 상품 정보 (성공시, 필수)

Product

Parameter Type Mandatory Limit sample Description
log_time String M 14 20160321154451 구매 이력 시간 (YYYYMMDDHHMMSS)
appid String M 10 OA00012345 AID
product_id String M 10 0000044056 인앱상품ID
charge_amount Number M 6 300000 구매 상품 금액
tid String O 100 201012226_01047637315_00000239 구매요청시 개발사가 발급한 TID
detail_pname String O 100 커스텀 상품명 구매요청시 필요한 상세 상품명(product_name)을 입력했을 경우 리턴되는 값
선택 입력된 값이 없을 때는 ‘X’ 가 설정됨
bp_info String O 1024 utm_source=onestore&utm_medium=iap&utm_campaign=20160325_promotion 개발자의 Application Server 가 확인하기 위한 정보

Status

Code Description
0 성공
9 조회결과가 없거나 파라미터 및 시스템 오류

Detail

Code Description Note
0000 성공
1000 필수 파라미터 부족 조회 요청시 TXID, APPID, signdata 중 파라미터가 부족할 때 발생하는 코드
9100 결제정보 조회결과 없음 signdata로 구매한 이력이 없을 경우
9113 전자영수증 데이터 유효성 검증 오류
9999 시스템 오류 시스템 에러는 IAP 내부 오류로써 발생할 경우 개발자센터에 문의 필요

Sample

{
	"status" : 0,
	"detail" : "0000",
	"message" : "정상검증완료", 
	"count" : 1,
	"product" : [{
		"log_time" : "20120321154451", 
		"appid" : "OA12345678", 
		"product_id" : "0900012345", 
		"charge_amount" : 1000,
		"tid" : "201012226_01047637315_00000239",
		"detail_pname" : "커스텀 상품명",
		"bp_info" : "X"}]
}

유의사항

Android app 에서는 다양한 방법을 통해 아이템에 대한 부정 취득을 시도할 수 있으므로 App 서버에서는 IAP Server로부터 전달되는 응답의 내용을 추가적으로 확인하여 아이템 발급에 대한 처리를 할 수 있어야 한다. App 서버에서는 다양한 부정 취득 시도를 막기 위해서 하기와 같은 방법을 사용하기를 강력 권장한다.

  • App에서 아이템 발급을 요청한 상품의 정보와 전자영수증 검증API를 통해 응답된 정보 (appid, product_id, charge_amount 등)가 일치하는지 여부를 확인
  • 구매 이력 시간(log_time)을 확인하여 일정 시간 이상(5분 이내 권장) 지난 구매 건에 대해서는 아이템 발급을 거부
  • 특정 TID에 대해 Item 발급이 정상적으로 처리된 경우, 해당 이력을 저장한 후에 동일한 TID로 Item 발급 요청이 오는 경우는 부정한 재시도로 판단하고 해당 아이템 발급 요청을 거부
  • 결제중 Application의 비정상적인 종료나 네트워크 오류가 발생하는 경우, sendCommandRequest 메소드를 이용하여 구매 내역을 확인 후 구매한 아이템을 사용할 수 있도록 하는 로직을 권장함.

Clone this wiki locally