한국어
Search
K

ONE store In-App支付服务器API (API V7)

概要

ONE store In-App支付服务器API是指用于查询在ONE store中支付的In-App商品的数据或变更支付状态的Open API。 为了使用该API,需要进行OAuth认证。

HOST Domain

本文中使用的Host Domain如下:
ONE store环境
Host Domain
验证(开发)
商用
本文中使用的域名是,国内和全球通用的域名。
仅在韩国服务的现有App/游戏的域名则保持原有的。(apis.onestore.co.kr)

市场分类

● Request header中已新增市场分类代码(x-market-code)。
● 如果在全球范围内提供服务,则必须在header中添加市场分类代码。
● 如果没有市场分类代码,会议韩国服务(默认值)来调用。
市场分类代码
服务国家
MKT_ONE
韩国
MKT_GLB
除韩国外

ONE store OAuth

OAuth概要

为了联动ONE store服务器Open API,需要进行OAuth认证。
  • ONE store OAuth V2的理解
    • AccessToken是通过ONE store的Server Open API可以获得的值,在调用ONE store提供的Server Open API时作为认证value使用
    • 默认情况下,AccessToken有效期为3600秒,如果有效期满或不足600秒时,可调用getAccessToken()发放新的AccessToken。
      • 现有的AccessToken也可在有效期结束前使用。
      • 由于是多数AccessToken发行的方式,因此每个开发公司的服务instance都可以获取并使用不同的AccessToken。
  • 一般联动流程如下
  • 获得AccessToken的过程(1号)只需在API调用时发生认证错误时调用即可。
对于ONE store中的In-App支付服务器API的调用,可使用Authorization Bearer Scheme,调用示例如下:
GET /v7/apps/com.onestore.game.goindol/purchases/inapp/products/product01/SANDBOXT000120004476 HTTP/1.1
Host: sbpp.onestore.co.kr
Authorization: Bearer 680b3621-1234-1234-1234-8adfaef561b4
Authorization Header与上述示例一样必须正确输入,Bearer + 空白 + AccessToken应区分大小写。 Bearer的值是通过调用getAccessToken()获得的AccessToken值。
错误示例
Authorization: 680b3621-1234-1234-1234-8adfaef561b4
Authorization: bearer 680b3621-1234-1234-1234-8adfaef561b4
Authorization: Bearer <680b3621-1234-1234-1234-8adfaef561b4>
Authorization:Bearer680b3621-1234-1234-1234-8adfaef561b4

OAuth API详情

确认client_id 及client_secret
client_id和 client_secret的值可通过点击ONE store开发者中心注册的App的In-App信息 > "认证及许可证"按钮确认。

发放AccessToken

  • URI : /v7/oauth/token
  • Method: POST
  • Request Parameter: Form格式
    Parameter Name
    Description
    Example
    client_id
    一般来说和packageName相同
    com.onestore.game.goindol
    client_secret
    在开发者中心上架应用软件时发放的client secret 值
    vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=
    grant_type
    固定值
    client_credentials
  • 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
  • Example
POST /v7/oauth/token HTTP/1.1
Host: apis.onestore.com
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 : JSON格式
    Element Name
    Data Type
    Data Size
    Description
    client_id
    String
    255
    OAuth认证client_id
    access_token
    String
    36
    AccessToken
    token_type
    String
    6
    只提供bearer方式
    expires_in
    Integer
    10
    token有效期, 单位 : 秒(second)
    scope
    String
    1024
    token使用范围
  • Example
{
"client_id":"com.onestore.game.goindol",
"access_token":"680b3621-1234-1234-1234-8adfaef561b4",
"token_type":"bearer",
"expires_in":3010,
"scope":"DEFAULT"
}
  • 发放示例
curl -v -X POST -H "Content-Type: application/x-www-form-urlencoded" https://sbpp.onestore.co.kr/v7/oauth/token -d "grant_type=client_credentials" -d "client_id=com.onestore.game.goindol" -d "client_secret=vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI="
> POST /v7/oauth/token HTTP/1.1
> Host: sbpp.onestore.co.kr
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/x-www-form-urlencoded;charset=UTF-8
> Content-Length: 35
>
* upload completely sent off: 35 out of 35 bytes
< HTTP/1.1 200 200
< Date: Wed, 02 May 2018 02:52:42 GMT
< Server: Apache< Connection: close
< Transfer-Encoding: chunked
< Content-Type: application/json;charset=UTF-8
<
* Closing connection 0
{"client_id":"com.onestore.game.goindol","access_token":"680b3621-1234-1234-1234-8adfaef561b4","token_type":"bearer","expires_in":3600,"scope":"DEFAULT"}
因为验证(开发)环境和商用环境的AccessToken是独立管理的,因此需要根据不同环境分类管理AccessToken。

服务器API详情

getPurchaseDetails (购买商品详情查询)

  • Desc : 查询购买的ONE store管理型商品的详细信息。 购买完成时,需使用收到的ONE store purchaseToken(购买token)查询。 通过包月型商品的purchaseToken查询时,将接收查询失败(NoSuchData)的响应。
  • URI : /v7/apps/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}
  • Method : GET
  • Request Parameter : Path Variable格式
    • String packageName : 调用 API的应用软件包名 (Data Size : 128)
    • String productId : 商品ID (Data Size : 150)
    • String purchaseToken : 购买token (Data Size : 20)
  • 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 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body :
  • Response Body : JSON格式
    Element Name
    Data Type
    Data Size
    Description
    consumptionState
    Integer
    1
    已购商品的消费状态 (0: 未消费, 1: 消费)
    developerPayload
    String
    200
    开发公司提供的支付固有标识符
    purchaseState
    Integer
    1
    购买状态 ( 0: 购买完成, 1: 取消完成)
    purchaseTime
    Long
    13
    购买时间 (ms)
    purchaseId
    String
    20
    购买ID
    acknowledgeState
    Integer
    1
    确认购买状态( 0: Not Acknowledged, 1: Acknowledged)
    quantity
    Integer
    2
    购买数量
  • Example
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"consumptionState": 0,
"developerPayload": "developerPayload",
"purchaseState": 0,
"purchaseTime": 1345678900000,
"purchaseId": "17070421461015116878",
"acknowledgeState": 0,
"quantity": 2
}

getRecurringPurchaseDetails (包月型商品订单详情查询)

  • Desc : 查询购买的ONE store包月型商品的自动支付状态和最后的购买状态的详细信息。 购买完成时,需使用收到的ONE store purchaseToken(购买token)查询。通过管理型商品的purchaseToken查询时,将接收查询失败(NoSuchData)的响应。
  • URI : /v7/apps/{packageName}/purchases/auto/products/{productId}/{purchaseToken}
  • Method : GET
  • Request Parameter : Path Variable格式
    • String packageName : 调用 API的应用软件包名 (Data Size : 128)
    • String productId : 商品ID (Data Size : 150)
    • String purchaseToken : 购买token (Data Size : 20)
  • 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 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
"startTime": 1345678900000,
"expiryTime": 1345678999999,
"nextPaymentTime": 1345688000000,
"autoRenewing": true,
"cancelReason": 1,
"cancelledTime": 1345679000000,
"acknowledgeState": 0,
"lastPurchaseId":"15081718460701027851",
"lastPurchaseState": 0
}
可根据以下条件判断客户是否有权使用包月型商品的内容。
  • 如果当前时间小于或等于expiryTime(已购商品的使用终止时间),或者lastPurchaseState(最后自动支付的购买状态)为0(购买完成)状态, Ex) expiryTime >= 当前时间 AND lastPurchaseState == 0

acknowledgePurchase (确认已购商品)

  • Desc : 将购买的管理型或包月型商品变更为购买确认状态。
  • URI : /v7/apps/{packageName}/purchases/all/products/{productId}/{purchaseToken}/acknowledge
  • Method : POST
  • Request Parameter : Path Variable格式
    • String packageName : 调用 API的应用软件包名 (Data Size : 128)
    • String productId : 商品ID (Data Size : 150)
    • String purchaseToken : 购买token (Data Size : 20)
  • 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 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : JSON 형식
    Element Name
    Data Type
    Required
    Description
    developerPayload
    String
    false
  • Example :
    {
    "developerPayload": "your payload"
    }
  • Response Body : JSON格式 传回以下格式的响应,以便在成功处理API时更直观地判断是否处理完成。如果API处理失败,将传回标准错误响应。
    Element Name
    Data Type
    Data Size
    Description
    code
    String
    -
    响应代码
    message
    String
    -
    响应信息
    result
    Object
    -
  • Example :
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
    "result" : {
    "code" : "Success",
    "message" : "Request has been completed successfully."
    }
    }
ONE store自动取消3天内未调用acknowledgePurchase API的购买订单。
因此,开发公司必须调用相应API,可通过SDK API或服务器API进行处理。
但是,consumePurchase API被调用的购买订单会被判断为acknowledge,不会取消购买。

consumePurchase (消费已购商品)

  • Desc : 将购买的管理型商品状态更改为消费状态。
  • URI : /v7/apps/{packageName}/purchases/inapp/products/{productId}/{purchaseToken}/consume
  • Method : POST
  • Request Parameter : Path Variable格式
    • String packageName :调用 API的应用软件包名 (Data Size : 128)
    • String productId : 商品ID (Data Size : 150)
    • String purchaseToken : 购买token (Data Size : 20)
  • 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 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : JSON 형식
    Element Name
    Data Type
    Required
    Description
    developerPayload
    String
    false
  • Example :
    {
    "developerPayload": "your payload"
    }
  • Response Body : JSON 형식
    传回以下格式的响应,以便在成功处理API时更直观地判断是否处理完成。如果API处理失败,将传回标准错误响应。
    Element Name
    Data Type
    Data Size
    Description
    code
    String
    -
    响应代码
    message
    String
    -
    响应信息
    result
    Object
    -
  • Example :
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
    "result" : {
    "code" : "Success",
    "message" : "Request has been completed successfully."
    }
    }

cancelRecurringPurchase (请求解除自动支付)

  • Desc : 请求解除包月型商品的自动支付。使用订阅型商品的purchaseToken查询时, 将接收查询失败(NoSuchData)响应。
  • URI : /v7/apps/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/cancel
  • Method : POST
  • Request Parameter : Path Variable格式
    • String packageName : 调用 API的应用软件包名 (Data Size : 128)
    • String productId : 商品ID (Data Size : 150)
    • String purchaseToken : 购买token (Data Size : 20)
  • 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 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 无
  • Response Body : JSON格式 传回以下格式的响应,以便在成功处理API时更直观地判断是否处理完成。如果API处理失败,将传回标准错误响应。
Element Name
Data Type
Data Size
Description
code
String
-
响应代码
message
String
-
响应信息
result
Object
-
  • Example :
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
    "result" : {
    "code" : "Success",
    "message" : "Request has been completed successfully."
    }
    }

reactiveRecurringPurchase (请求取消解除自动支付)

  • Desc : 取消解除包月型商品的自动支付的请求。使用订阅型商品的purchaseToken查询时,将接收查询失败(NoSuchData)响应。
  • URI : /v7/apps/{packageName}/purchases/auto/products/{productId}/{purchaseToken}/reactivate
  • Method : POST
  • Request Parameter : Path Variable格式
    • String packageName : 调用 API的应用软件包名 (Data Size : 128)
    • String productId : 商品ID (Data Size : 150)
    • String purchaseToken : 购买token (Data Size : 20)
  • 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 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 无
  • Response Body : JSON格式 传回以下格式的响应,以便在成功处理API时更直观地判断是否处理完成。如果API处理失败,将传回标准错误响应。
Element Name
Data Type
Data Size
Description
code
String
-
响应代码
message
String
-
响应信息
result
Object
-
  • Example :
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
    "result" : {
    "code" : "Success",
    "message" : "Request has been completed successfully."
    }
    }

getVoidedPurchases (查询取消的订单)

  • Desc : 查询取消的订单
  • URI : /v7/apps/{packageName}/voided-purchases
  • Method : GET
  • Request Parameter : Path Variable格式
    • String packageName : 调用 API的应用软件包名 (Data Size : 128)
  • Request Parameter (Optional) : Query String格式
    • String continuationKey : 取消购买的数量较多时,ONE store服务器返回该值。 当响应中有continuationKey时,通过再次调用getVoidedPurchases的同时传递continuationKey,可能会收到额外的取消购买历史记录。 (Data Size : 41)
    • String startTime : 取消购买日期的搜索开始的时间 (milliseconds). 以当前时间为准,仅可设置到过去1个月内;单独使用startTime时,endTime设置成以startTime基准的未来1个月。 (Data Size : 13)
    • String endTime : 取消购买日期的搜索结束的时间 (milliseconds). 不能超过当前时间,单独使用endTime时,startTime设置成以endTime为基准的过去1个月。 (Data Size : 13)
    • unsigned integer maxResults : 最大查询次数 default 100 (Data Size : 3)
  • 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 680b3621-1234-1234-1234-8adfaef561b4");
    Request.setHeader("Content-Type", "application/json");
    Request.setHeader("x-market-code", "MKT_GLB");
  • Request Body : 无
  • Response Body
Element Name
Data Type
Data Size
Description
continuationKey
String
41
取消购买数量大于最大查询数量时返回。在后续请求中,通过设置接收的continuationKey进行调用,可以查询后续历史记录。
voidedPurchaseList
-
purchaseId
String
20
购买ID
purchaseTime
Long
13
购买时间(ms)
voidedTime
Long
13
购买取消时间(ms)
purchaseToken
String
20
购买Token
marketCode
String
-
市场分类代码
  • Example :
    HTTP/1.1 200 OK
    Content-type: application/json;charset=UTF-8
    {
    "continuationKey": "continuationKey",
    "voidedPurchaseList ": [
    {
    "purchaseId": "19062709124410111299",
    "purchaseTime": 1345678900000,
    "voidedTime": 1345688900000,
    "purchaseToken": "19062709124410111299",
    "marketCode": "MKT_ONE"
    },
    {
    "purchaseId": "19062709124410111300",
    "purchaseTime": 1345679900000,
    "voidedTime": 1345878900000,
    "purchaseToken": "19062709124410111299",
    "marketCode": "MKT_ONE"
    }
    ]
    }

getSubscriptionDetail (订阅型商品订单详情查询)

  • Desc : 查询订阅型商品的订单详情。
  • URI : /v7/apps/{packageName}/purchases/subscription/products/{productId}/{purchaseToken}
  • Method : GET
  • Request Parameter : Path Variable格式
    • String packageName : 调用 API的应用软件包名 (Data Size : 128)
    • String productId : 商品ID (Data Size : 150)
    • String purchaseToken : 购买token (Data Size : 20)
  • 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