第三方支付

第三方支付？

第三方付款是指銷售商（以下稱為開發者）在不使用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環境（https://sbpp.onestore.net ）下是否正常傳送交易紀錄。
(E) [開發者] 將開發的最終版安裝包（APK）上傳至ONE store開發者中心，並連接商用環境。
- 首先連接開發者商用環境和ONE store商用環境（https://apis.onestore.net)
- 接著連接商用環境下，接入開發者想要使用的第三方支付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://sbpp.onestore.net

商用

https://iap-apis.onestore.net

連動流程

傳送第三方支付的購買紀錄

外部付款購買記錄傳輸API已更新。（send3rdPartyPurchase-p1 ）
使用現有外部付款購買記錄傳輸格式時，無法在美國分發APP.
在美國通過外部付款服務於App時，必須使用send3rdPartyPurchase-p1 格式。

用戶在應用程式中購買商品時，應用程式會在連動時取得所需資訊。（參考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）

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

一般與packageName一致

com.onestore.game.goindol

client_secret

註冊應用程式時發放的client secret值

vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=

grant_type

固定值

client_credentials

Example

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

AccessToken 發放結果

client_id

String

255

OAuth 認證 client_id

access_token

String

token_type

String

只提供 bearer方式

expires_in

Integer

token 有效期限，單位為秒（second）

scope

String

1024

token 使用範圍

Example

{
    "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/{packageName}/send/p1
Method: POST
Parameters: String packageName : 呼叫API的應用程式包的名稱。 (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

Request.setHeader("Authorization", " Bearer <Access-Token>");
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

{
    "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

true

數據保存狀況（0 : 成功）

responseMessage

String

500

true

developerOrderId

String

100

true

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

Example

{
    "responseCode": "Success",
    "responseMessage": "The request has been completed successfully.",
    "developerOrderId": "your_order_id_1234567890"
}

cancel3rdPartyPurchase （取消第三方支付的購買紀錄）

Desc: 取消開發商通過第三方支付平台購買的紀錄。
URI: https://{host}/v2/purchase/developer/{packageName}/cancel
Method: POST
Parameters: String packageName : 呼叫API的應用程式包名稱。 (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

Request.setHeader("Authorization", " Bearer <Access-Token>");
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

true

1970年1月1日之後購買商品的時間（單位：ms）

cancelCd

String

true

取消原因代碼（參考代碼表）

Example

{
    "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

{
    "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

{
    "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

/**
* 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

ONE store SKT

com.skt.skaf.A000Z00040

ONE store KT

com.kt.olleh.storefront

ONE store LG U+

com.lguplus.appstore

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

/**
* 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";
}

其他

結算

請參考[這裡]了解結算相關內容。

技術 / 政策諮詢

詳細的諮詢事項請發信向ONE store開發者中心詢問。（devhelper@onestore.net）

Last updated 1 month ago