인앱결제 레퍼런스

서버 응답코드

• 원스토어 서비스에서 애플리케이션으로 전송되는 응답코드는 <표 1>에 정의되어 있습니다.

• AIDL과 인앱결제 API V5(SDK V17)를 적용한 앱에서는 <표 1>의 모든 응답코드에 대해 처리를 해야 합니다. <표 1> 인앱결제 API 호출 시 서버 응답코드

  Response Code	Value	Description	How to handle
  RESULT_OK	0	성공
  RESULT_USER_CANCELED	1	결제가 취소되었습니다.	사용자의 명시적인 결제 취소시 발생됩니다.
  RESULT_SERVICE_UNAVAILABLE	2	구매에 실패했습니다. (단말 또는 서버 네트워크 오류가 발생하였습니다)	일시적인 네트워크 오류입니다. 개발사에서는 적절한 alert 메시지로 잠시 후 다시 이용할 수 있도록 사용자에게 가이드합니다.
  RESULT_BILLING_UNAVAILABLE	3	구매에 실패했습니다. (구매 처리 과정에서 오류가 발생하였습니다)	원스토어 구매 관련 로직 처리 시 발생하는 오류입니다. 이 문제가 발생하면 발생한 로그 정보 및 구매 정보와 함께 원스토어 담당자에게 문의합니다.
  RESULT_ITEM_UNAVAILABLE	4	구매에 실패했습니다. (상품이 판매중이 아니거나 구매할 수 없는 상태입니다)	구매요청시 개발자 센터에 판매중이 아니거나 구매할 수 없는 상태의 상품입니다. 개발자 센터에 등록된 상품이 올바른지 확인해야합니다.
  RESULT_DEVELOPER_ERROR	5	구매에 실패했습니다. (올바르지 않은 구매 요청입니다)	구매요청 및 다른 요청을 보낼 시에 정상적이지 않은 파라미터로 호출 할 경우에 발생되는 에러입니다. 테스트 단계에서 해결되어야 할 오류이며 실제 퍼블리싱된 앱에서는 절대 발생해선 안 됩니다. 이 문제가 발생하면 개발사 앱 코드를 검증합니다.
  RESULT_ERROR	6	구매에 실패했습니다. (정의되지 않은 기타 오류가 발생했습니다)	원스토어 구매 관련 로직 처리 시 발생하는 오류입니다. 이 문제가 발생하면 발생한 로그 정보 및 구매 정보와 함께 원스토어 담당자에게 문의합니다.
  RESULT_ITEM_ALREADY_OWNED	7	구매에 실패했습니다. (이미 아이템을 소유하고 있습니다)	관리형 상품은 소비하기 전에 재구매할 수 없습니다. 영구성 형태의 상품은 재구매가 불가하기 때문에 이 오류 메시지가 나타나는 것은 정상이며, 만약 소비성 아이템인데 이 오류 메시지가 나온다면 구매 후의 소비로직을 검증해야 합니다.
  RESULT_ITEM_NOT_OWNED	8	구매에 실패했습니다. (아이템을 소유하고 있지 않아 comsume 할 수 없습니다)	관리형 상품 소비 시에 이미 소비되거나 구매되지 않은 상품에 대해서 소비요청을 진행할 경우 발생합니다. 소비되지 않은 소비성 아이템에 대해서 상품소비를 진행해야합니다.
  RESULT_FAIL	9	결제에 실패했습니다. 결제 가능 여부 및 결제 수단 확인 후 다시 결제해주세요.	원스토어 결제 관련 로직 처리 시 발생하는 오류입니다. 이 문제가 발생하면 발생한 로그 정보 및 구매 정보와 함께 원스토어 담당자에게 문의합니다.
  RESULT_NEED_LOGIN	10	구매에 실패했습니다. (구매를 위해 원스토어 로그인이 필요합니다)	원스토어 계정이 등록되지 않았을 경우 발생합니다. 개발사에서는 AIDL의 getLoginIntent 및 SDK의 launchLoginFlowAsync 메서드를 호출하여 원스토어 로그인을 진행합니다. 개발사에서 원스토어 로그인을 제공하지 않을 시에는 적절한 alert 메시지로 원스토어 앱을 구동하도록 사용자에게 가이드합니다.
  RESULT_NEED_UPDATE	11	구매에 실패했습니다. (원스토어 서비스앱의 업데이트가 필요합니다)	원스토어 서비스 앱이 설치 또는 업데이트가 필요한 상황입니다. 개발사에서는 SDK의 launchUpdateOrInstallFlow 메서드를 호출하여 원스토어 서비스 앱의 설치 또는 업데이트를 진행합니다. 개발사에서는 원스토어 설치/업데이트를 명시적으로 제공하지 않을 시에는 적절한 alert 메시지로 원스토어 앱을 구동하도록 사용자에게 가이드합니다.
  RESULT_SECURITY_ERROR	12	구매에 실패했습니다. (비정상 앱에서 결제가 요청되었습니다)	호출규격에 포함되어 있는 패키지명 정보가 실제 호출한 앱과 다를 시에 발생합니다. 또한 개발사 앱의 사이닝 값과 개발자센터에 등록되어 있는 앱의 사이닝 값이 다를 경우에도 발생합니다. 개발사에서는 AIDL호출시 개발자센터에 등록되어있는 앱의 패키지명을 올바르게 넣도록 해야하며, 개발자센터 샌드박스 테스트가 아닐때에는 앱이 사이닝 된 상태에서 호출해야 합니다.

isBillingSupported() - 지원여부 조회

• 이 메서드는 원스토어 인앱결제 지원여부를 조회합니다.

• 원스토어 인앱결제를 이용하기 전 해당 메서드를 호출하여 상태 확인을 할 수 있습니다. <표 2> isBillingSupported 요청에 대한 응답 데이터

  Type	Description
  Integer	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).

getProductDetails() - 상품정보 조회

• 이 메서드는 애플리케이션 ID(AID)에 해당하는 상품 상세정보를 반환합니다.

• 전달되는 productDetailList 키에 맵핑되는 String ArrayList 의 상세 정보는 <표 4>에 정리되어 있습니다. <표 3> getProductDetails 요청에 대한 응답 데이터

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  productDetailList	String ArrayList	상품정보 조회시 반환받는 상품상세정보로, JSON 형태의 String 리스트로 구성됩니다. <표 4>를 참고하세요. [ { "productId": "your_custom_pid", "type": "inapp", "price": "1000", "priceCurrencyCode": "KRW", "title": "Sample Title" }, { "productId": "your_custom_pid2", "type": "inapp", "price": "1000", "priceCurrencyCode": "KRW", "title": "Sample Title" }]
  [ { "productId": "your_custom_pid", "type": "inapp", "price": "1000", "priceCurrencyCode": "KRW", "title": "Sample Title" }, { "productId": "your_custom_pid2", "type": "inapp", "price": "1000", "priceCurrencyCode": "KRW", "title": "Sample Title" }]

  <표 4> getProductDetails 요청에 대한 응답 데이터 중 productDetailList 에 대한 JSON 필드 설명

  Field	Type	Description
  productId	String	상품의 ID입니다.
  type	String	상품의 상품군 정의 값으로 "inapp", "auto" 값을 이용합니다. inapp : 관리형 상품(managed product)으로, 소멸 처리가 가능한 상품 auto : 월정액 상품(subscriptoin)
  price	String	상품의 가격입니다.
  priceCurrencyCode	String	price에 대한 통화코드로서 원스토어 결제에서는 KRW(원) 단위로 제공됩니다.
  title	String	상품의 제목입니다.

getPurchaseIntent() - 구매 요청

• 이 메서드는 구매요청을 위한 메서드입니다. 응답값으로 구매 진행을 위한 purchaseIntent를 반환합니다.

  <표 5> getPurchaseIntent 요청에 대한 응답 데이터

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  purchaseIntent	Intent	원스토어 결제 프로세스를 진행하기 위한 Intent 데이터입니다. 전달받은 Intent를 앱 화면 상에서 Activity.startActivityForResult()를 통해 호출하면 결제가 진행됩니다.

  앱에서 purchaseIntent를 이용하여 Activity.startActivityForResult()를 호출하면, 원스토어 결제 프로세스를 진행합니다. 결제가 완료되면 구매 요청에 대한 최종 응답을 Intent로 받게됩니다.

  <표 6> 구매(결제) 완료 시 onActivityResult()로 전달되는 Intent 필드

  Field	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  purchaseData	String (JSON)	구매 상세 정보입니다. JSON형태의 String 데이터로 상세 정보는 <표 7>을 참고하시기 바랍니다. {"orderId": "TSTORE0003_20180110095711854446569571914", "packageName": {packageName}, "productId": "your_custom_pid", "purchaseTime": 1345678900000, "purchaseId": "18011009571110118593", "developerPayload": "something not special"}
  {"orderId": "TSTORE0003_20180110095711854446569571914", "packageName": {packageName}, "productId": "your_custom_pid", "purchaseTime": 1345678900000, "purchaseId": "18011009571110118593", "developerPayload": "something not special"}
  purchaseSignature	String	개발자의 개인 키로 서명된 구매 상세 정보의 서명을 포함한 String입니다. 구매상태 정보가 변조되지 않았는지 앱에서 해당 값으로 체크할 수 있습니다.

  <표 7> 구매 완료 시 onActivityResult()로 전달되는 Intent 필드 내 purchaseData 필드 상세 내용

  Key	Type	Description
  orderId	String	결제 트랜잭션에 대한 고유 식별자인 결제 ID입니다. Sandbox 결제환경에서는 "ONESTORE"라는 prefix가 있고, 상용(상용테스트 포함) 결제환경에서는 사업자별로 prefix가 생성됩니다. Prefix는 변경 또는 추가될 수 있으므로 이를 이용하여 정상 결제 여부를 판단해서는 안됩니다. Sandbox (40자리) : ONESTORE01_20181010201622210521210113575 상용 (40자리) : TSTORE0001_20181010201622210521210113575
  packageName	String	구매가 요청된 앱의 패키지 네임입니다.
  productId	String	인앱상품의 상품 ID입니다.
  purchaseTime	long	1970년 1월 1일 이후 상품 구매가 이루어진 시간입니다(단위: ms).
  purchaseId	String	원스토어에서 해당 구매 건을 고유하게 식별할 수 있는 구매 ID입니다. 상용(상용테스트 포함) 결제환경과 Sandbox(개발용) 결제환경을 구분하기 위해 Sandbox에서 결제된 purchaseId에는 "SANDBOX" Prefix가 추가됩니다. Prefix는 변경 또는 추가될 수 있으므로 이를 이용하여 정상 결제 여부를 판단해서는 안됩니다. Sandbox (20자리) : SANDBOX1810102016211 상용 (20자리) : 18101020162111624520
  developerPayload	String	구매건을 식별하기 위해 개발사에서 관리하는 식별자입니다. getPurchaseIntent 호출 시 값을 전달할 수 있으며, 구매 완료 시 동일한 값을 purchaseData의 developerPayload 필드로 응답합니다.

getPurchaseIntentExtraParam() - 구매 요청

• 이 메서드를 이용하면, 구매요청 시 <표 8>에 정의되어 있는 내용들을 추가로 전달 할 수 있습니다. 추가 파라미터인 gameUserId와 promotionApplicable 항목의 경우, 프로모션의 참여를 제한(ex. 중복 참여 제한)하는 용도로 사용됩니다. 이 메서드의 응답값으로 구매 진행을 위한 purchaseIntent를 반환합니다.

  <표 8> Extra Bundle data

  Bundle Key	Type	Description
  gameUserId	String	개발사 앱을 이용하는 유저의 고유 식별 번호를 전달합니다. 해당 값은 프로모션 참가 가능 여부 및 프로모션 사용 여부를 판가름 하는 key value로 사용됩니다.
  promotionApplicable	boolean	프로모션 참가 가능 여부를 전달합니다. true : gameUserId로 전달된 사용자는 단일 프로모션에 1회 참가가 가능합니다. false : gameUserId로 전달된 사용자는 프로모션에 참가가 불가능 합니다.

  gameUserId, promotionApplicable 파라미터는 Optional 값으로 원스토어 사업부서 담당자와 프로모션에 대해 사전협의가 된 상태에서만 사용하여야 하며, 일반적인 경우에는 값을 보내지 않아도 됩니다. 또한, 사전협의가 되어 값을 보낼 경우에도 개인정보보호 이슈가 없도록 gameUserId는 hash된 unique한 값으로 전송하여야 합니다.

  앱에서 purchaseIntent를 이용하여 Activity.startActivityForResult()를 호출하면, 원스토어가 결제 프로세스를 진행합니다. 결제가 완료될 경우 구매 요청에 대한 최종 응답을 Intent로 받게됩니다. 응답 Intent에 반환되는 데이터는 <표 10>에 정리되어 있습니다.

  <표 9> getPurchaseIntentExtraParam 요청에 대한 응답 데이터

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  purchaseIntent	Intent	원스토어 결제 프로세스를 진행하기 위한 Intent 데이터입니다. 전달받은 Intent를 앱 화면 상에서 Activity.startActivityForResult()를 통해 호출하면 결제가 진행됩니다.

  <표 10> 구매 완료 시 onActivityResult()로 전달되는 Intent 필드 내 purchaseData 필드 상세 내용

  Field	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  purchaseData	String (JSON)	구매 상세 정보입니다. JSON형태의 String 데이터로 상세 정보는 <표 7>을 참고하시기 바랍니다. {"orderId": "TSTORE0003_20180110095711854446569571914", "packageName": {packageName}, "productId": "your_custom_pid", "purchaseTime": 1345678900000, "purchaseId": "18011009571110118593", "developerPayload": "something not special"}
  {"orderId": "TSTORE0003_20180110095711854446569571914", "packageName": {packageName}, "productId": "your_custom_pid", "purchaseTime": 1345678900000, "purchaseId": "18011009571110118593", "developerPayload": "something not special"}
  purchaseSignature	String	개발자의 개인 키로 서명된 구매 상세 정보의 서명을 포함한 String입니다. 구매상태 정보가 변조되지 않았는지 앱에서 해당 값으로 체크할 수 있습니다.

  <표 11> 구매 완료 시 onActivityResult()로 전달되는 Intent 필드 내 purchaseData 필드 상세 내용

  Key	Type	Description
  orderId	String	결제 트랜잭션에 대한 고유 식별자인 결제 ID입니다. Sandbox 결제환경에서는 "ONESTORE"라는 prefix가 있고, 상용(상용테스트 포함) 결제환경에서는 사업자별로 prefix가 생성됩니다. Prefix는 변경 또는 추가될 수 있으므로 이를 이용하여 정상 결제 여부를 판단해서는 안됩니다. Sandbox (40자리) : ONESTORE01_20181010201622210521210113575 상용 (40자리) : TSTORE0001_20181010201622210521210113575
  packageName	String	구매가 요청된 앱의 패키지 네임입니다.
  productId	String	인앱상품의 상품 ID입니다.
  purchaseTime	long	1970년 1월 1일 이후 상품 구매가 이루어진 시간입니다(단위: ms).
  purchaseId	String	원스토어에서 해당 구매 건을 고유하게 식별할 수 있는 구매 ID입니다. 상용(상용테스트 포함) 결제환경과 Sandbox(개발용) 결제환경을 구분하기 위해 Sandbox에서 결제된 purchaseId에는 "SANDBOX" Prefix가 추가됩니다. Prefix는 변경 또는 추가될 수 있으므로 이를 이용하여 정상 결제 여부를 판단해서는 안됩니다. Sandbox (20자리) : SANDBOX1810102016211 상용 (20자리) : 18101020162111624520
  developerPayload	String	구매건을 식별하기 위해 개발사에서 관리하는 식별자입니다. getPurchaseIntent 호출 시 값을 전달할 수 있으며, 구매 완료 시 동일한 값을 purchaseData의 developerPayload 필드로 응답합니다.

getLoginIntent() - 로그인 요청

• 원스토어 로그인을 위한 메서드입니다. <표 1>의 응답코드 중 RESULT_NEED_LOGIN 응답을 받을 경우, 원스토어 로그인을 유도해야 합니다.

• 응답값으로 원스토어 로그인을 위한 loginIntent 를 반환합니다.

  <표 12> getLoginIntent 요청에 대한 응답 데이터

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  purchaseIntent	Intent	원스토어 로그인 프로세스를 진행하기 위한 Intent 데이터입니다. 전달받은 Intent를 앱 화면 상에서 Activity.startActivityForResult()를 통해 호출하면 로그인이 진행됩니다.

  앱에서 loginIntent를 이용하여 Activity.startActivityForResult()를 호출하면, 원스토어 로그인 프로세스를 진행합니다. 로그인이 완료될 경우 로그인 요청에 대한 최종 응답을 받게됩니다. 응답 데이터는 <표 13>에 정리되어 있습니다.

  <표 13> 로그인 완료 시 onActivityResult()로 응답 값

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고). 성공할 경우 다른 API를 계속 이용할 수 있습니다. 실패는 고객이 로그인 화면을 취소하였거나(ex. Back key), 원스토어의 정상 회원이 아닌 경우 입니다. 실패한 경우 고객에게 원스토어를 구동하여 회원 상태를 확인하거나, 원스토어 고객센터로 연락하여 문제를 해결하도록 해야 합니다.

getPurchases() - 구매내역 조회

• 고객의 구매내역을 조회하는 메서드입니다.

• 고객의 구매내역 중 소비(consume) 처리가 되지 않은 관리형 상품(managed product) 목록과 유효한 월정액 상품(subscription) 목록을 반환합니다.

  <표 14> getPurchases 요청에 대한 응답 데이터

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  productIdList	ArrayList<String>	구매된 인앱상품의 productId String 리스트입니다. ["your_custom_pid", "your_custom_pid2"]
  ["your_custom_pid", "your_custom_pid2"]
  purchaseDetailList	ArrayList<String>	인앱상품 구매 상세정보입니다. JSON형태의 String 리스트로 전달되며, 자세한 내용은 <표 15>을 참고하시기 바랍니다. [{ "orderId": "TSTORE0003_20180110095711854446569571914", "packageName": {packageName}, "productId": "your_custom_pid", "purchaseTime": 1345678900000, "purchaseState": 0, "recurringState": 0, "purchaseId": "18011009571110118593", "developerPayload": "something not special" }, { "orderId": "TSTORE0003_20180110095711854446569571915", "packageName": {packageName}, "productId": "your_custom_pid2", "purchaseTime": 1345678920000, "purchaseState": 1, "recurringState": 0, "purchaseId": "18011009571110118594", "developerPayload": "something really special" }]
  [{ "orderId": "TSTORE0003_20180110095711854446569571914", "packageName": {packageName}, "productId": "your_custom_pid", "purchaseTime": 1345678900000, "purchaseState": 0, "recurringState": 0, "purchaseId": "18011009571110118593", "developerPayload": "something not special" }, { "orderId": "TSTORE0003_20180110095711854446569571915", "packageName": {packageName}, "productId": "your_custom_pid2", "purchaseTime": 1345678920000, "purchaseState": 1, "recurringState": 0, "purchaseId": "18011009571110118594", "developerPayload": "something really special" }]
  purchaseSignatureList	ArrayList<String>	앱에서 이루어진 구매내역의 서명 String 리스트입니다. ["sign1", "sign2"]
  ["sign1", "sign2"]
  continuationKey	String	구매내역 결과가 많을 경우 원스토어 서버에서 해당 값을 반환합니다. 응답에 continuationKey가 있을 경우, getPurchases를 다시 호출하면서 continuationKey를 전달하면 추가 구매내역을 전달받을 수 있습니다.

  <표 15> getPurchase 요청에 대한 응답 데이터 중 purchaseDetailList 에 대한 JSON 필드 상세 내용

  Key	Type	Description
  orderId	String	결제 트랜잭션에 대한 고유 식별자인 결제 ID입니다. Sandbox 결제환경에서는 "ONESTORE"라는 prefix가 있고, 상용(상용테스트 포함) 결제환경에서는 사업자별로 prefix가 생성됩니다. Prefix는 변경 또는 추가될 수 있으므로 이를 이용하여 정상 결제 여부를 판단해서는 안됩니다. Sandbox (40자리) : ONESTORE01_20181010201622210521210113575 상용 (40자리) : TSTORE0001_20181010201622210521210113575
  packageName	String	구매가 요청된 앱의 패키지 네임입니다.
  productId	String	인앱상품의 상품 ID입니다.
  purchaseTime	long	1970년 1월 1일 이후 상품 구매가 이루어진 시간입니다(단위: ms).
  purchaseState	int	현재 구매 상태 값입니다. 0 : 정상구매 상태 1 : 구매취소 상태
  recurringState	int	월정액 상품의 상태 값입니다. 0 : 정상가입 상태 1 : 해지예약 상태 -1 : 월정액 상품이 아닌 경우
  purchaseId	String	원스토어에서 해당 구매 건을 고유하게 식별할 수 있는 구매 ID입니다. 상용(상용테스트 포함) 결제환경과 Sandbox(개발용) 결제환경을 구분하기 위해 Sandbox에서 결제된 purchaseId에는 "SANDBOX" Prefix가 추가됩니다. Prefix는 변경 또는 추가될 수 있으므로 이를 이용하여 정상 결제 여부를 판단해서는 안됩니다. Sandbox (20자리) : SANDBOX1810102016211 상용 (20자리) : 18101020162111624520
  developerPayload	String	구매건을 식별하기 위해 개발사에서 관리하는 식별자입니다. getPurchaseIntent 호출 시 값을 전달할 수 있으며, 구매 완료 시 동일한 값을 purchaseData의 developerPayload 필드로 응답합니다.

consumePurchase() - 상품소비 요청

• 관리형 상품(managed product)에 대한 소비(consume) 처리를 요청하는 메서드입니다. 상품 소비 요청 시에는 구매정보에 포함되어 있는 purchaseId를 이용하며, 소비 처리에 성공할 경우 응답 데이터에 해당 purchaseId 값을 반환합니다. <표 16> consumePurchase 요청에 대한 응답 데이터

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  purchaseId	String	원스토어에서 해당 구매 건을 고유하게 식별할 수 있는 구매 ID입니다.

manageRecurringProduct() - 월정액 상품 상태변경 요청

• 월정액 상품(subscription)에 대한 '해지 예약' 및 '해지 예약 취소'를 요청하는 메서드입니다. 요청 시에는 구매정보에 포함되어 있는 purchaseId를 이용하며, 요청이 처리된 경우 응답 데이터에 해당 purchaseId 값을 반환합니다. <표 17> manageRecurringProduct 요청에 대한 응답 데이터

  Key	Type	Description
  responseCode	int	성공했을 경우 0을, 실패했을 경우 에러코드를 전달합니다(에러코드는 <표 1> 참고).
  purchaseId	String	원스토어에서 해당 구매 건을 고유하게 식별할 수 있는 구매 ID입니다. 상용(상용테스트 포함) 결제환경과 Sandbox(개발용) 결제환경을 구분하기 위해 Sandbox에서 결제된 purchaseId에는 "SANDBOX" Prefix가 추가됩니다. Prefix는 변경 또는 추가될 수 있으므로 이를 이용하여 정상 결제 여부를 판단해서는 안됩니다. Sandbox (20자리) : SANDBOX1810102016211 상용 (20자리) : 18101020162111624520