원스토어 인앱결제 API V6 업그레이드 가이드 (서버)
개요
본 문서는 원스토어 인앱결제 API V5(SDK V17)에서 API V6(SDK V19)로 업그레이드 하는 과정에 대해 설명합니다.
인앱결제 API V6(SDK V19) 주요 특징 및 변경사항
Server API
purchaseToken 추가
purchaseToken 은 SDK V19 버전에서 구매건을 대표하는 Key 값으로 SDK V17 API 에서 기준 Key로 사용되었던 purchaseId 를 대체하는 구매 기준 Key입니다.
purchaseToken 은 구매 성공시 결과 응답에서 확인할 수 있으며 관리형 상품의 경우 purchaseToken과 purchaseId가 1:1 매핑되고 자동결제형 상품의 경우 1:N으로 맵핑됩니다.
acknowledge API 추가
정상적인 구매 완료 후 개발사가 이를 인지하였음을 확인하기 위한 acknowledge API가 추가되었습니다.
원스토어는 3일 이내에 acknowledgePurchase API가 호출되지 않은 구매건을 자동으로 취소합니다. 따라서 개발사는 반드시 구매완료 후 SDK API 또는 Server API를 통하여 acknowledge API를 호출해야합니다.
단, consumePurchase API가 호출된 구매건은 묵시적으로 acknowledge가 되었다고 판단하고 구매취소를 처리하지 않습니다.
SDK V17에서 consume 요청 하지 않는 상황(자동결제 상품 첫결제, 관리형 상품의 재결제를 막기 위하여 소비 처리 안하는 상황 등)에서 반드시 추가적으로 acknowledge API 호출을 구현해야 합니다.
표준오류 응답규격 변경
SDK V19 의 표준오류 응답규격이 가독성 향상을 위하여 문자 기반으로 변경되었습니다.
마켓구분코드추가
원스토어 내 인앱 상품의 Multi 마켓 출시를 대비하여 마켓구분코드가 추가되었습니다.
API 상세 규격 및 변경 사항은 아래에서 확인 가능합니다.
PNS
3.0.0 버전의 메시지 규격 추가
원스토어내 인앱 상품의 Multi 마켓 출시를 대비하여 메시지 규격이 추가되었습니다.
메시지 버전 3.0.0 은 SDK V17 버전에서도 사용가능합니다.
개발자 센터에서 앱별로 전송받을 메시지의 버전(2.0.0/3.0.0)을 선택할 수 있도록 기능이 추가되었습니다.
메시지 버전 변경시 즉시 반영되어 이후 메시지는 신규 선택된 메시지 버전으로 송신됩니다.
미 설정 시 하위호환성 유지를 위하여 기존 메시지 버전(2.0.0)으로 송신됩니다.
개발자 센터에서 Dummy 메시지 테스트 발송 기능 추가
샌드박스 및 상용 환경에서 구매/취소가 발생 하였을때만 메시지가 발송되어 PNS 서버 구축 및 테스트에 불편함을 주는것을 개선하기 위하여 개발자센터에서 더미 메시지 송신 기능이 추가 되었습니다.
메시지 버전 3.0.0 규격은 아래에서 확인 가능합니다.
업그레이드 절차
개발사에서 직접 관리하는 구매 DB에 purchaseToken 추가
SDK V19 에서는 purchaseToken을 기본 Key로 사용하기 때문에 기존 구매를 관리하는 데이터에 purchaseToken을 추가로 저장 관리해야 합니다.
purchaseToken은 SDK API 를 통해 구매 완료되는 시점 또는 SDK API getPurchase API 응답 결과로 전달 받을 수 있습니다.
원스토어 신규 인앱결제 SDK 적용
SDK V19 버전을 지원하는 신규 인앱결제 SDK 를 적용해야 합니다.
Acknowledge 호출 로직 추가
구매 완료 후 3일 이내로 Acknowledge 되지 않은 구매는 자동 취소됩니다. 단, consume 처리된 구매건은 Acknowledge 되었음으로 간주하기 때문에 취소되지 않습니다.
따라서 구매 완료 후 consume 처리 하지 않은 모든 구매건에 대하여 Acknowledge 요청해야 합니다.
ServerAPI V6 적용
(Server API를 사용하지 않는경우 생략 가능합니다.)
ServerAPI V6는 기존과 동일한 OAuth 정책과 환경을 사용하기 때문에 V5 ServerAPI 와 동일한 방식으로 호출하면 됩니다.
기존 V5 ServerAPI에서 변경된 점은 아래에서 확인가능합니다.
PNS 신규 메시지 버전(3.0) 적용
(이미 PNS 서비스를 사용하고 있고 메시지 규격 변경을 원하지 않는경우 생략 가능합니다.)
PNS 3.0.0 메시지 버전 규격을 처리 할 수 있도록 PNS 서버 구축 합니다.
개발자 센터에서 PNS 노티 URI를 셋팅한 후 정상적으로 통신이 가능한지 Test 발송합니다.
확인 후 저장하여 설정을 반영합니다.
PNS 메시지는 네트워크 통신의 문제 등으로 지연/유실 될 가능성이 있기 때문에 아이템 지급 기준으로 사용하면 안됩니다.
업그레이드 이후 예상되는 문제 해결 방법
SDK V17 구매 건의 ServerAPI 이용방법
SDK V17 에서 결제된 구매건은 별도로 purchaseToken이 발급되지 않습니다. 따라서 기존 V5 ServerAPI 를 사용하시기 바랍니다.
단, V17 구매건의 경우 구매 성공시 자동으로 acknowledge 되었음으로 간주합니다.
SDK V19 구매 건의 ServerAPI 이용방법
구매 성공시 응답받은 purchaseToken 을 이용하여 V6 ServerAPI를 사용하시기 바랍니다.
하위 호환성 보장을 위하여 purchaseId 로 기존 V5 ServerAPI를 사용 할 수 있으나
acknowledge API 호출 등 프로세스에 변경되는 부분이 있으니 V6 ServerAPI 로 전환을 적극 권장합니다.
V17 구매 성공 후 소비되지 않은 상황에서 V19 버전 단말로 소비 요청하는 경우 (또는 그 반대케이스)
기존과 같이 인앱결제 SDK consume API를 이용하시면 소비가 가능합니다.
단, ServerAPI를 이용하여 소비 요청할 경우 SDK V17 구매건은 V5 ServerAPI SDK, SDK V19 구매건은 V6 ServerAPI 를 이용하시면 됩니다.
Last updated
