# 第三方支付 ### **第三方支付？** 第三方付款是指銷售商（以下稱為開發者）在不使用ONE store應用程式提供的結帳模組（In-App結帳SDK）的情況，直接連接第三方支付平台提供的支付服務。 ## **第三方支付使用方法** ### **傳送交易明細** * 開發者即使用第三方支付，也須將第三方支付交易明細（購買紀錄、取消記錄）發送給ONE store，開發者有必要對此進行開發和審核。 * 開發者傳送的第三方支付交易明細會用於ONE store 排行榜和服務，以及作為ONE store和開發者之間的結算資料。 ### **開發與審核流程**

* (A) \[開發者] 進入ONE store開發者中心> Apps >點選 “商品註冊” 鍵，註冊新增應用程式。 * 在“商品註冊”畫面中選取“使用第三方支付平台”的選項，設為“使用”。

* 確認“第三方支付之同意”視窗中所示內容，設為同意（“確認”）。

* (B) \[開發者] 在“商品註冊”畫面中收到 OAuth Key（Client\_secret）。

* (C) \[開發者] 開發時需參考API伺服器規範。 * 開發OAuth AccessToken發放、傳送交易紀錄等。 * (D) \[開發者] 務必確認在Sandbox環境（）下是否正常傳送交易紀錄。 * (E) \[開發者] 將開發的最終版安裝包（APK）上傳至ONE store開發者中心，並連接商用環境。 * 首先連接開發者商用環境和ONE store商用環境（) * 接著連接商用環境下，接入開發者想要使用的第三方支付PG。 * (F) \[開發者] 向ONE store申請審核。 * (G) \[ONE store] 務必確認在開發者應用程式中完成支付後，是否能在商用環境下發送交易紀錄。 * (H) \[ONE store] 要求開發者取消用於審核的第三方支付款項。（向開發者聯絡人傳送相應郵件） * (I) \[開發者] 取消該交易的支付。 * (J) \[ONE store] 確認在商用環境下開發者的交易取消紀錄是否能正常發送，如果無誤就表示通過審核。 * (K) \[開發者] 上架通過審核的應用程式。 ### **發送交易紀錄的條件** * 需發送交易紀錄的標準如下： * 使用第三方支付的情況 * 使用第三方支付服務直接購買商品 * 使用第三方支付服務儲值應用內要支付的貨幣\* （\*應用內貨幣：只能在相關應用可儲值，只能購買相關應用內的商品的貨幣） * 使用開發者自設的支付貨幣\*\*來購買商品（\*\*開發者自設的支付貨幣：不僅是相關應用程序，還可以同樣開發公司的其他應用或Web等其他渠道適用第三方支付購買，在多個應用中可以使用的結帳方式） * 除外情况（不使用第三方支付服务） * 通過開發者內部推廣活動建立的支付平台（如免費優惠券，現金點數）來購買商品 * 未在One Store發布的國家範圍內而是在其他國家發生交易時 * 根據購買ID(developerOrderId)來確認交易紀錄。 * 所開發的應用程式接入第三方支付服務，須在“第三方支付完成”後，向用戶提供購買ID。（支付完成畫面及郵件通知） * ONE store審核組須根據購買ID確認相對應用程式的第三方支付交易紀錄是否正常發送給ONE store。 * 發送國家代碼和貨幣代碼時，請注意以下事項： * 對於One Store發布的國家中出現的交易，則以 ISO\_3166-1\_alpha-2為基準發送國家代碼。 * 貨幣代碼則以國家代碼為基準，根據 ISO\_4217 進行發送，如果交易的貨幣與國家貨幣不同，則將其轉換為國家貨幣進行發送。（搜尋Google，截至當日00時） * 國家代碼為KR時，Request Header的x-market-code則發送至MKT\_ONE。 * 國家代碼不是KR時，Request Header的x-market-code則發送至MKT\_GLB。 * ONE store審核組進行確認程序，如無法傳達正確的總供應價格，可進行驗證退貨或停止銷售處理。 ## **伺服器API** ### **什麼是第三方支付伺服器API?** * 開發者支付完成（成功）後，須將相對數據發送給ONE store，同步支付紀錄。同時，支付成功且完成同步的交易如需更改相關數據（取消交易）時，同樣需要發送相關交易紀錄。 * 發送給ONE store的第三方支付購買或取消的交易內容會反應於ONE store 應用程式的排行榜，面向一般顧客公開，以及用於ONE store和開發者之間的結算資料。 * 第三方支付連動API是指，為了將在開發商中所進行的第三方支付結帳購買明細及取消明細傳送至ONE store而提供的API。 * send3rdPartyPurchase （傳送第三方支付的購買紀錄） * cancel3rdPartyPurchase （取消第三方支付的購買紀錄） * 為了各個API的連動，應先進行OAuth認證，在進行OAuth認證前應先收到client\_id和client\_secret。 ### **連動環境** * ONE store API伺服器根據目的分成開發環境（Sandbox）和商用環境。 * 開發環境（Sandbox）： * 套用與商用 API同規則的虛擬連動環境。 * 開發者開發可連接ONE store和伺服器API後，將應用程式在開發者中心正式上架之前，連動開發環境進行測試。 * 該流程中，開發者傳送的支付訊息不適用於排名或結算。 * 商用環境： * 實際服務的環境，應同步用戶的完成支付或取消紀錄。 * 開發者在商用環境中傳送的支付數據會反應於結算業務，如果在商用環境中進行支付測試，須取消相關交易。 * 開發環境和商用環境的host資訊如下。 | **環境** | **Service Host** | | ------- | --------------------------------------------------------------- | | Sandbox | | | 商用 | [https://iap-apis.onestore.net](https://iap-apis.onestore.net/) | ### 連動流程 #### **傳送第三方支付的購買紀錄** {% hint style="warning" %} * 外部付款購買記錄傳輸API已更新。（send3rdPartyPurchase-p1 ） * 使用現有外部付款購買記錄傳輸格式時，無法在美國分發APP. * 在美國通過外部付款服務於App時，必須使用send3rdPartyPurchase-p1 格式。 {% endhint %} * 用戶在應用程式中購買商品時，應用程式會在連動時取得所需資訊。（參考4. Reference Code） * 將應用程式取得的資訊和用戶的購買請求傳送給開發者伺服器。 * 開發者伺服器通過第三方支付（PG或其他應用商店所提供的應用程式內支付程序）處理支付，將支付結果傳送給相關應用程式。 * 同時，將透過第三方支付進行的購買紀錄傳送到ONE store API 伺服器。 * （如果ONE store的 OAuth 存取令牌到期）先取得OAuth 存取令牌（AccessToken），再連動API。 * 建議保存API連動結果做為狀態值，連動失敗時重試。

#### **取消第三方支付的購買紀錄** * 如連動ONE store的購買紀錄被取消，應將通過第三方支付平台取消的紀錄傳送到ONE store API伺服器。 * （如果ONE store的 OAuth 存取令牌到期）先取得OAuth 存取令牌（AccessToken），再連動API。 * 建議保存API連動結果做為狀態值，連動失敗時重試。

### **ONE store OAuth** #### 概要 * 連動ONE store 交易相關伺服器 API時，必須通過 OAuth認證取得 AccessToken （存取令牌）。 * AccessToken的有效時間為3600秒，如果有效期間到期或只剩下600秒以下時，再次呼叫 getAccessToken()，可取得新令牌。 * 已有的AccessToken也可以使用到有效期限結束為止。 * 開發者可重複取得AccessToken，因此根據開發商的服務實例（instance），可以取得並使用不同的AccessToken。 * 基本流程如下： * 取得AccessToken的流程（1）是如果呼叫API時出現認證錯誤時採用即可。 * 為了呼叫ONE store的伺服器API，使用 Authorization Bearer的呼叫範例如下。（Bearer值是指呼叫 getAccessToken()後取得的 AccessToken）

```json POST /v2/purchase/developer/com.onestore.game.goindol/send HTTP/1.1 Host: apis.onestore.net Authorization: Bearer 680b3621-1234-1234-1234-8adfaef561b4 ... ``` #### **getAccessToken (取得AccessToken)** * **Desc**: 發放用於使用伺服器API的AccessToken。 * **URI:** /v6/oauth/token * **Method**: POST, PUT * **Request Header** | **Parameter Name** | **Description** | **Example** | | ------------------ | ------------------------------------------------------------- | ----------------------------------------------- | | Content-Type | 請求Http 時，務必把Content Type設定為 application/x-www-form-urlencoded | Content-Type: application/x-www-form-urlencoded | | x-market-code | | x-market-code: MKT\_GLB | * **Request Body** | **Element Name** | **Description** | **Example** | | ---------------- | -------------------------- | -------------------------------------------- | | client\_id | 在開發者中心註冊應用時發放的 Client ID 值 | 0000042301 | | client\_secret | 註冊應用程式時發放的client secret值 | vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI= | | grant\_type | 固定值 | client\_credentials | * **Example** ```json POST /v6/oauth/token HTTP/1.1 Host: iap-apis.onestore.net Content-Type: application/x-www-form-urlencoded;charset=UTF-8 x-market-code: MKT_GLB grant_type=client_credentials&client_id=com.onestore.game.goindol&client _secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI= ``` * **Response Body** | **Element Name** | **Data Type** | **Data Size** | **Description** | | ---------------- | ------------- | ------------- | ----------------------- | | status | String | 7 | AccessToken 發放結果 | | client\_id | String | 255 | OAuth 認證 client\_id | | access\_token | String | 36 |

| | token\_type | String | 6 | 只提供 bearer方式 | | expires\_in | Integer | 10 | token 有效期限，單位為秒（second） | | scope | String | 1024 | token 使用範圍 | * **Example** ```json { "status":"SUCCESS", "client_id":"com.onestore.game.goindol", "access_token":"680b3621-1234-1234-1234-8adfaef561b4", "token_type":"bearer", "expires_in":3010, "scope":"DEFAULT" } ``` ## **伺服器API 詳細內容** 將第三方支付的購買明細及取消明細傳送給ONE store伺服器的詳細內容。 #### **send3rdParyPurchase-p1 (傳送第三方支付的購買明細)** * **Desc**: 傳送開發商通過第三方支付購買的明細。 * **URI**: /v6/purchase/developer/{clientId}/send/p1 * **Method**: POST * **Parameters**: String clientId : 調用 API的應用軟件Client ID (Data Size : 128) * **Request Header** | **Parameter Name** | **Data Type** | **Required** | **Description** | | ------------------ | ------------- | ------------ | -------------------------------- | | Authorization | String | true | 通過Access Token 取得的 access\_token | | Content-Type | String | true | application/json | | x-market-code | String | FALSE | | **Example** ```json Request.setHeader("Authorization", " Bearer "); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body**
| **Element Name** | **Data Type** | **Data Size** | **Required** | **Description** | | ----------------------- | ------------- | ------------- | ------------ | ---------------------------------------------------------------------- | | countryCode | String | 2 | TRUE | 交易的納稅國家代碼以 ISO\_3166-1\_alpha-2 為基本傳送。 | | currencyCode | String | 3 | TRUE | 以 ISO\_4217 為基本傳送 | | developerOrderId | String | 100 | true |

為了識別各項購買事項的開發商ID

（必須是Unique值，重複儲存時會發生錯誤，参考Error Response）

| | developerProductList \[ | | | true | | | developerProductId | String | 150 | true | 開發商應用程式內的商品ID | | developerProductName | String | 200 | true | 開發商應用程式內的商品名稱 | | developerProductPrice | Double | 10 | true | 開發商應用程式內的商品價格 (不含稅價格) | | developerProductQty | Integer | 10 | true | 開發商應用程式內的商品購買數量 | | ] | | | | | | simOperator | String | 20 | true | 手機上取得的simOperator 資料（如果沒有的會以UNKNOWN\_SIM\_OPERATOR傳送） | | totalSuppliedAmount | Double | 20 | true | 總供應價格（除去稅金的結算對象金額） | | purchaseTime | Long | 19 | true | 1970年1月1日之後購買商品的時間（單位：ms）（傳送無效的時間時會出現錯誤9002，參考Error Response） | * **Example** ```json { "countryCode": "KR", "currencyCode": "KRW", "developerOrderId": "your_order_id_1234567890", "developerProductList": [ { "developerProductId": "your_product_id_1111", "developerProductName": "게임아이템A", "developerProductPrice": 5000.0, "developerProductQty": 2 }, { "developerProductId": "your_product_id_2222", "developerProductName": "게임아이템B", "developerProductPrice": 5000.0, "developerProductQty": 1 } ], "simOperator": "45005", "totalSuppliedAmount": 15000.0, "purchaseTime": 1345678920000 } ``` * **Response Body** | **Element Name** | **Data Type** | **Data Size** | **Required** | **Description** | | ---------------- | ------------- | ------------- | ------------ | ---------------- | | responseCode | String | 50 | true | 數據保存狀況（0 : 成功） | | responseMessage | String | 500 | true | | | developerOrderId | String | 100 | true | 為了識別各項購買事項的開發商ID | * **Example** ```json { "responseCode": "Success", "responseMessage": "The request has been completed successfully.", "developerOrderId": "your_order_id_1234567890" } ``` #### **cancel3rdPartyPurchase （取消第三方支付的購買紀錄）** * **Desc**: 取消開發商通過第三方支付平台購買的紀錄。 * **URI**: https\://{host}/v2/purchase/developer/{clientId}/cancel * **Method**: POST * **Parameters**: String clientId : 調用 API的應用軟件Client ID (Data Size : 128) * **Request Header**


Parameter Name	Data Type	Required	Description
Authorization	String	true	通過Access Token API 取得的 access_token
Content-Type	String	true	application/json
x-market-code	String	FALSE

* **Example** ```json Request.setHeader("Authorization", " Bearer "); Request.setHeader("Content-Type", "application/json"); Request.setHeader("x-market-code", "MKT_GLB"); ``` * **Request Body** | **Element Name** | **Data Type** | **Data Size** | **Required** | **Description** | | ---------------- | ------------- | ------------- | ------------ | ------------------------------------------------------------- | | developerOrderId | String | 100 | true |

為了識別各項購買事項的開發商ID

（重複請求取消時會發生錯誤，参考Error Response）

| | cancelTime | Long | 19 | true | 1970年1月1日之後購買商品的時間（單位：ms） | | cancelCd | String | 30 | true | 取消原因代碼（參考代碼表） | * **Example** ```json { "developerOrderId" : "your_order_id_1234567890", "cancelTime" : 1345678920000, "cancelCd" : "TRD_CANCEL_USER" } ``` * **Response Body**
| **Element Name** | **Data Type** | **Data Size** | **Required** | **Description** | | ---------------- | ------------- | ------------- | ------------ | ---------------- | | responseCode | String | 50 | true | 取消成功與否（0 : 成功） | | responseMessage | String | 500 | true | | | developerOrderId | String | 100 | true | 為了識別各項購買事項的開發商ID | * **Example** ```json { "responseCode": "Success", "responseMessage": "Request has been completed successfully.", "developerOrderId": "test1695105094231" } ``` ## **代碼表** #### **取消原因代碼 (cancelCd)** | **carrierCd** | **取消原因** | **備註** | | ----------------- | -------- | ------------ | | TRD\_CANCEL\_USER | 用戶申請取消購買 |

| | TRD\_CANCEL\_TEST | 取消測試購買 |

| | TRD\_CANCEL\_ETC | 其他 |

| #### **Error Response** 伺服器API正常回應以外發生Error時，另外以JSON形式傳送Response，參考以下內容： * **Response Body : JSON形式** | **Element Name** | **Data Type** | **Description** | | ------------------ | ------------- | --------------- | | error | Object | 錯誤訊息 | |

code

| Integer | 錯誤代碼 | |

message

| String | 錯誤消息 | * **Example** ```json { "error": { "code": "AccessTokenExpired", "message": "The access token was expired. Expired access token." } } ``` #### **Error Codes**

에러코드	에러메시지 (한국어)	에러메시지 (영어)
RequiredValueNotExist	필수값이 존재하지 않습니다. [ fields1, fields2, ... ]	Request parameters are required. {0}
NoSuchData	조회된 결과값이 존재하지 않습니다.	The requested data could not be found.
InvalidRequest	입력된 값이 유효하지 않습니다. [ fields1, fields2, ... ]	Request parameters are invalid. {0}
InternalError	정의되지 않은 오류가 발생하였습니다.	An undefined error has occurred.
DuplicatedPurchase	중복된 구매데이터입니다.	The purchase are duplicated.
Not3rdPartyPurchaseProduct	외부결제로 등록된 상품이 아닙니다.	The product is not registered with external payment.
Invalid3rdPartyCancelState	외부결제 구매내역 전송/취소가 불가능한 판매상태입니다.	It is in a sales state where it is impossible to send or cancel the purchase details of external payment.
NotExistPurchaseOrCannotCancel	취소할 구매데이터가 존재하지 않거나 취소할 수 없는 상태입니다.	The purchase data to be canceled does not exist or cannot be canceled.
Invalid3rdPartyMarketCodeOne	국가/통화 코드를 확인해주세요. 대한민국이 아닌 국가에서 발생한 거래내역은 마켓 구분 코드 MKT_GLB로 전송해야 합니다.	Please check the country/currency code. For transactions outside Korea, use MKT_GLB as the market code.
Invalid3rdPartyMarketCodeGlb	국가/통화 코드를 확인해주세요. 대한민국에서 발생한 거래내역은 마켓 구분 코드 MKT_ONE으로 전송해야 합니다.	Please check the country/currency code. For transactions in Korea, use MKT_ONE as the market code.
NotSupport3rdPartyCountryCode	원스토어에서 판매중인 국가의 거래내역이 아닙니다.	These transaction details are not related to distribution countries.
NotMatch3rdPartyCurrencyCode	거래가 발생한 국가의 국가 통화로 거래내역을 전송해야 합니다. ({0} 만 가능합니다)	Use the local currency code for transaction details. (Only the {0} is allowed.)

## **Reference Code** 本指南包含客戶端開發內容，以支援傳送在 ONE store 銷售的第三方支付應用程式的交易明細。開發商可以確認以下提供的內容，可直接實現功能或參考範例代碼並使用。 ### **取得應用程式安裝程式資料** * 在ONE store安裝的應用程式總共會帶有8個安裝套件（install package）資料，參考下表。 * 如果使用以下代碼則是通過ONE store安裝程式（Installer）安裝應用程式，必須將相對應用程式的支付訊息傳送給ONE store。 **Example** ```json /** * Returns the package name of the application that installed a package. * The OneStore has many installer package names. * Please check below list of package names. * * Google Play : com.android.vending * * ONE Store : * 1. com.skt.skaf.A000Z00040 * 2. com.kt.olleh.storefront * 3. com.lguplus.appstore * 4. com.onestorecorp.gaa.storeapp * 5. com.dti.folderlaunche * * If you read null string, return the "UNKNOWN_INSTALLER". * * @param context application context * @return Name of installer package name or "UNKNOWN_INSTALLER" */ public static String getInstallerPackageName(@NonNull Context context) { if (context != null) { Context applicationContext = context.getApplicationContext(); PackageManager pm = applicationContext.getPackageManager(); final String installPackageName = pm.getInstallerPackageName(applicationContext.getPackageName()); if (!TextUtils.isEmpty(installPackageName)) { return installPackageName; } } return "UNKNOWN_INSTALLER"; } ```

编号	Installer	Installer Package Name
1	ONE store SKT	com.skt.skaf.A000Z00040
2	ONE store KT	com.kt.olleh.storefront
3	ONE store LG U+	com.lguplus.appstore
4	ONE store GLOBAL	com.onestorecorp.gaa.storeapp com.dti.folderlaunche

### **取得手機電信業者資訊** * 從USIM 卡取得手機電信業者資訊，通過ONE store第三方支付交易明細的傳送API進行傳達。 * 要傳達的手機電信業者資訊是以MCC+MNC組合的SIM Operator訊息，由5～6位數字組成。 * 如果像Wi-Fi Tablet一樣的設備無法取得SIM Operator的情況下，可傳送 "**UNKNOWN\_SIM\_OPERATOR**" 即可。 Example ```json /** * Returns the MCC+MNC (mobile country code + mobile network code) of the provider of the SIM. 5 or 6 decimal digits * If you can't read of SinOpreater, return the "UNKOWN_SIM_OPERATOR". * * @param context application context * @return MCC+MNC information or "UNKNOWN_SIM_OPERATOR" */ public static String getSimOperator(@NonNull Context context) {if (context != null) { Context applicationContext = context.getApplicationContext(); TelephonyManager telephonyManager = (TelephonyManager) applicationContext.getSystemService(Context.TELEPHONY_SERVICE); if (telephonyManager != null && telephonyManager.getSimState() == TelephonyManager.SIM_STATE_READY) { return telephonyManager.getSimOperator(); } } return "UNKNOWN_SIM_OPERATOR"; } ``` ## **其他** ### **結算** * 請參考[\[這裡\]](https://onestore-dev.gitbook.io/dev/cht/docs/payment/payment_type/third-party)了解結算相關內容。 ## **技術 / 政策諮詢** * 詳細的諮詢事項請發信向ONE store開發者中心詢問。（）