# 원스토어 인앱결제 API V6 업그레이드 가이드 (서버)

### **개요**  <a href="#id-apiv6" id="id-apiv6"></a>

본 문서는 원스토어 인앱결제 API V5(SDK V17)에서 API V6(SDK V19)로 업그레이드 하는 과정에 대해 설명합니다.

#### 인앱결제 API V6(SDK V19) 주요 특징 및 변경사항  <a href="#id-apiv6-apiv6-sdkv19" id="id-apiv6-apiv6-sdkv19"></a>

**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 상세 규격 및 변경 사항은 아래에서 확인 가능합니다.

[원스토어 인앱 서버 API (V6)](https://onestore-dev.gitbook.io/dev/tools/billing/old-version/v19/api-api-v6)

[ServerAPI 상세 변경 내역](https://onestore-dev.gitbook.io/dev/tools/billing/old-version/v19/undefined-6/api-v6/serverapi)

#### PNS <a href="#id-apiv6-pns" id="id-apiv6-pns"></a>

**3.0.0 버전의 메시지 규격 추가**

* 원스토어내 인앱 상품의 Multi 마켓 출시를 대비하여 메시지 규격이 추가되었습니다.
* 메시지 버전 3.0.0 은 SDK V17 버전에서도 사용가능합니다.

**개발자 센터에서 앱별로 전송받을 메시지의 버전(2.0.0/3.0.0)을 선택할 수 있도록 기능이 추가되었습니다.**

* 메시지 버전 변경시 즉시 반영되어 이후 메시지는 신규 선택된 메시지 버전으로 송신됩니다.
* 미 설정 시 하위호환성 유지를 위하여 기존 메시지 버전(2.0.0)으로 송신됩니다.

**개발자 센터에서 Dummy 메시지 테스트 발송 기능 추가**

* 샌드박스 및 상용 환경에서 구매/취소가 발생 하였을때만 메시지가 발송되어 PNS 서버 구축 및 테스트에 불편함을 주는것을 개선하기 위하여 개발자센터에서 더미 메시지 송신 기능이 추가 되었습니다.

메시지 버전 3.0.0 규격은 아래에서 확인 가능합니다.

[PNS 메시지 상세 변경 내역](https://onestore-dev.gitbook.io/dev/tools/billing/old-version/v19/undefined-6/api-v6/pns)

<br>

### **업그레이드 절차** <a href="#id-apiv6" id="id-apiv6"></a>

#### **개발사에서 직접 관리하는 구매 DB에 purchaseToken 추가**  <a href="#id-apiv6-db-purchasetoken" id="id-apiv6-db-purchasetoken"></a>

SDK V19 에서는 purchaseToken을 기본 Key로 사용하기 때문에 기존 구매를 관리하는 데이터에 purchaseToken을 추가로 저장 관리해야 합니다.

purchaseToken은 SDK API 를 통해 구매 완료되는 시점 또는 SDK API getPurchase API 응답 결과로 전달 받을 수 있습니다.

#### 원스토어 신규 인앱결제 SDK 적용  <a href="#id-apiv6-sdk" id="id-apiv6-sdk"></a>

SDK V19 버전을 지원하는 신규 인앱결제 SDK 를 적용해야 합니다.

#### Acknowledge 호출 로직 추가  <a href="#id-apiv6-acknowledge" id="id-apiv6-acknowledge"></a>

구매 완료 후 3일 이내로 Acknowledge 되지 않은 구매는 자동 취소됩니다. 단, consume 처리된 구매건은 Acknowledge 되었음으로 간주하기 때문에 취소되지 않습니다.

따라서 구매 완료 후 consume 처리 하지 않은 모든 구매건에 대하여 Acknowledge 요청해야 합니다.

#### **ServerAPI V6 적용** <a href="#id-apiv6-serverapiv6" id="id-apiv6-serverapiv6"></a>

(Server API를 사용하지 않는경우 생략 가능합니다.)

ServerAPI V6는 기존과 동일한 OAuth 정책과 환경을 사용하기 때문에 V5 ServerAPI 와 동일한 방식으로 호출하면 됩니다.

기존 V5 ServerAPI에서 변경된 점은 아래에서 확인가능합니다.

[ServerAPI 상세 변경 내역](https://onestore-dev.gitbook.io/dev/tools/billing/old-version/v19/undefined-6/api-v6/serverapi)

#### PNS 신규 메시지 버전(3.0) 적용 <a href="#id-apiv6-pns-3.0" id="id-apiv6-pns-3.0"></a>

(이미 PNS 서비스를 사용하고 있고 메시지 규격 변경을 원하지 않는경우 생략 가능합니다.)

PNS 3.0.0 메시지 버전 규격을 처리 할 수 있도록 PNS 서버 구축 합니다.

개발자 센터에서 PNS 노티 URI를 셋팅한 후 정상적으로 통신이 가능한지 Test 발송합니다.

<figure><img src="https://1837360763-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fot0z57AnnXZ02C5qyePV%2Fuploads%2F2P6joQBvKlSsHaqhbspT%2Fimage.png?alt=media&#x26;token=0c0f1769-4fa5-4205-bc5e-3c4dc16539ca" alt=""><figcaption></figcaption></figure>

확인 후 저장하여 설정을 반영합니다.&#x20;

PNS 메시지는 네트워크 통신의 문제 등으로 지연/유실 될 가능성이 있기 때문에 아이템 지급 기준으로 사용하면 안됩니다.

### **업그레이드 이후 예상되는 문제 해결 방법** <a href="#id-apiv6" id="id-apiv6"></a>

#### **SDK V17 구매 건의 ServerAPI 이용방법**  <a href="#id-apiv6-sdkv17-serverapi" id="id-apiv6-sdkv17-serverapi"></a>

SDK V17 에서 결제된 구매건은 별도로 purchaseToken이 발급되지 않습니다. 따라서 기존 V5 ServerAPI 를 사용하시기 바랍니다.

단, V17 구매건의 경우 구매 성공시 자동으로 acknowledge 되었음으로 간주합니다.&#x20;

#### SDK V19 구매 건의 ServerAPI 이용방법 <a href="#id-apiv6-sdkv19-serverapi" id="id-apiv6-sdkv19-serverapi"></a>

구매 성공시 응답받은 purchaseToken 을 이용하여 V6 ServerAPI를 사용하시기 바랍니다.

하위 호환성 보장을 위하여 purchaseId 로 기존 V5 ServerAPI를 사용 할 수 있으나

acknowledge API 호출 등 프로세스에 변경되는 부분이 있으니 V6 ServerAPI 로 전환을 적극 권장합니다.

#### V17 구매 성공 후 소비되지 않은 상황에서 V19 버전 단말로 소비 요청하는 경우 (또는 그 반대케이스)  <a href="#id-apiv6-v17-v19" id="id-apiv6-v17-v19"></a>

기존과 같이 인앱결제 SDK consume API를 이용하시면 소비가 가능합니다.

단, ServerAPI를 이용하여 소비 요청할 경우 SDK V17 구매건은 V5 ServerAPI SDK,  SDK V19 구매건은 V6 ServerAPI 를 이용하시면 됩니다.

<br>