Using In-App Purchases on the Web

Overview

This document explains the integration method for using ONE store in-app purchases in a web environment.

Prerequisites

Membership Authentication Integration

To implement ONE store in-app purchases for Windows-based games/apps or PC/Mobile Web, membership authentication (login integration) is required. For detailed information, refer to the "Membership Authentication"

Firewall Policy Registration

To enable CallBackUrl calls, it is mandatory to register firewall policies between ONE store's payment server and the developer's server. Developers intending to use CallBackUrl must provide their server's IP information in advance.

  • Integration with port 80 or 443 of the developer's server is standard.

  • Firewall policy registration requires at least one business day to complete.

Integration Architecture

ONE store provides member-based services. Even in a web environment, user login is required for payment requests. After login, payments can be initiated. To avoid requiring users to log in repeatedly for each payment request, OAuth authentication is supported. All purchase/payment-related server APIs must use the OAuth Token (referred to as User Access Token) obtained during login.

Server APIs

ONE store web server APIs must be called using the issued User Access Token. When making HTTP calls, include the access token in the header.

Standard Response Codes

Code
message_kr
message_en
HTTP Status Code
대상API

UserNotExist

회원 정보가 존재하지 않습니다.

User does not exist.

404 - Not Found

공통

UserAccessTokenExpired

User Access Token이 만료되었습니다.

User Access Token has expired.

401 - Unauthorized

공통

UnsupportedDevice

상품이 해당 단말을 지원하지 않습니다.

The product does not support the device.

400 - Bad Request

공통

UnauthorizedUserAccess

해당 API에 접근권한이 없습니다.

Not authorized to this API.

403 - Forbidden

공통

Success

정상처리 되었습니다.

The request has been successfully completed.

200 - Success

consume/acknowledge

ServiceMaintenance

서비스 점검중입니다.

System maintenance is in progress.

503 - Service Temporarily Unavailable

공통

ResourceNotFound

요청한 자원이 존재하지 않습니다.

The requested resource could not be found.

404 - Not Found

공통

RequiredValueNotExist

필수값이 존재하지 않습니다. [ field1, field2, ... ]

Request parameters are required. [ field1, field2, ... ]

400 - Bad Request

공통

ProductNotExist

상품 정보가 존재하지 않습니다.

The product does not exist.

404 - Not Found

공통

NotSupportMultipleQuantity

복수 구매 요청은 관리형 상품으로 제한합니다.

Only Managed products are eligible for repeated purchase requests.

400 - Bad Request

requestPurchase

NoSuchData

조회된 결과값이 존재하지 않습니다.

The requested data could not be found.

404 - Not Found

단건조회 API

MethodNotAllowed

지원하지 않는 HTTP Method 입니다.

HTTP method not supported.

405 - Method Not Allowed

공통

InvalidUserAccessToken

User Access Token이 유효하지 않습니다.

User Access Token is invalid.

401 - Unauthorized

공통

InvalidUser

회원 정보가 유효하지 않습니다.

User information is not valid.

409 - Conflict

공통

InvalidRequest

입력값이 유효하지 않습니다. [ field1, field2, ... ]

Request parameters are invalid. [ field1, field2, ... ]

400 - Bad Request

공통

InvalidPurchaseState

구매내역이 존재하지 않거나, 구매완료 상태가 아닙니다.

Purchase history does not exist or is not completed.

409 - Conflict

consume/acknowledge

InvalidProduct

상품 정보가 유효하지 않습니다.

The product is not valid.

409 - Conflict

공통

InvalidContentType

잘못된 Content Type 입니다.

The request content-type is invalid.

415 - Unsupported Media Type

공통

InvalidConsumeState

소비상태 변경이 불가하거나, 이미 변경완료 되었습니다.

The purchase consumption status cannot be changed or has already been changed.

409 - Conflict

consume

InvalidAuthorizationHeader

Authorization 헤더의 값이 유효하지 않습니다.

Authorization header is invalid.

400 - Bad Request

공통

InternalError

정의되지 않은 오류가 발생하였습니다.

An undefined error has occurred.

500 - Internal Server Error

공통

ExceedQuantityMultiplePurchase

구매 요청이 가능한 개수를 초과하였습니다. (최대 10개)

Your purchase request has exceeded the quantity available. (Max. 10 items)

400 - Bad Request

requestPurchase

ExceedAmountMultiplePurchase

구매 요청이 가능한 금액을 초과하였습니다. (최대 50만원)

Your purchase request has exceeded the amount available. (Max. ₩500,000)

400 - Bad Request

requestPurchase

DeveloperPayloadNotMatch

구매요청 시 전달된 developerPayload값과 일치하지 않습니다.

The request developerPayload does not match the value passed in the purchase request.

400 - Bad Request

consume/acknowledge

AlreadyPurchased

이미 상품을 보유하였거나 함께 구매할 수 없는 상품을 보유중입니다.

You already have the product or a product that cannot be purchased together.

409 - Conflict

requestPurchase

AccessBlocked

요청이 차단되었습니다.

The request was blocked.

403 - Forbidden

공통

Standard Error Response

In case of error responses, codes and messages defined in the standard response codes are delivered.

Example

HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8
{
    "error" : {
        "code" : "NoSuchData",
        "message" : "The requested data could not be found."
    }
}

Product Type Code

Code

Name

Description

inapp

Consumable products

products that can be consumed

auto

Monthly auto-renewal products

Monthly automatic payment products

subscription

Subscription-based products

Subscription-based products

all

All products

Consumable products + Monthly auto-renewal products + Subscription products

requestPurchase

[API Spec.]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/{type}/products/{productId}/order

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/{type}/products/{productId}/order

Description

  • requesting the purchase of a specific in-app product.

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

The client ID of the app

type

String

Y

  • The in-app product type code for the purchase request.

  • Refer to Product Type Code

productId

String

Y

The in-app product ID for which the purchase is requested.

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

Element Name
Data Type
Data Size
Required
Description

prchsClientPocCd

String

50

Y

Purchase Request Client Classification Code: POC_PC : PC Payment POC_MOBILE : Mobile Payment

returnUrl

String

200

Y

Redirect URL for Receiving Payment Results

callbackUrl

String

200

N

REST API URL for Receiving Payment Results (Only for the Final Payment Result)

productName

String

50

N

In-App Product Name for Purchase Request (If not provided, the product name registered in the developer center will be used)

developerPayload

String

200

N

An identifier managed by the developer to identify the purchase transaction

quantity

Integer

N

Quantity of the product to be purchased (Default: 1)

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/inapp/products/p5000/order
Host: pcapis.onestore.net Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB
 
{
    "prchsClientPocCd": "POC_PC",
    "returnUrl": "https://onestorecorp.com",
    "callbackUrl": "https://onestorecorp.com",
    "productName": "금화100개",
    "developerPayload" : "1jkl2j3lk1lj",
    "quantity": 2
}

[ Response ]

Element Name
Data Type
Data Size
Description

purchaseId

String

20

Purchase ID

paymentUrl

String

200

Payment Request URL Information

paymentParam

String

-

Payment Request Parameter Information

Example

성공 시

{
   "purchaseId": "200406083435101108801",
   "paymentUrl": "https://onestorecorp.com",
   "paymentParam": "ABCDEDIAGJAFERasdfwerewrlkjasjflsdafj42352ds"
}



// 실패 시

{
    "error" : {
        "code" : "AlreadyPurchased",
        "message" : "You already have the product or a product that cannot be purchased together."
    }
}

getProductDetails

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/products/{type}

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/products/{type}

Description

  • Returns detailed information about in-app products available for sale.

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

type

String

Y

  • The in-app product type code for the purchase request.

  • Refer to Product Type Code

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

Element Name
Data Type
Data Size
Required
Description

productIdList [

String

150

Y

The in-app product ID specified during product registration in the developer center.

]

Example

POST /pc/v7/apps/com.onestorecorp.com.test/products/inapp
Host: 
pcapis.onestore.net

Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB

{
    "productIdList": ["다이아100_20170818000000", "루비300_20170818000000"]
}

[ Response ]

Element Name
Data Type
Data Size
Description

productDetailList [

-

List of product details

{

productId

String

150

In-app product ID for purchasable items

type

String

20

  • Product Type

  • Refer to Product Type Code

price

String

30

Product price

priceCurrencyCode

String

10

Currency denomination (e.g., KRW, USD)

title

String

-

Product name

priceAmountMicros

Long

-

Product price * 1M

}

]

Example

// 성공 시
{
    "productDetailList": [
        {
            "productId": "다이아100_20170818000000",
            "type": "inapp",
            "price": "1000",
            "priceCurrencyCode": "KRW",
            "title": "Sample Title",
            "priceAmountMicros": 1000000000
        },
        {
            "productId": "루비300_20170818000000",
            "type": "inapp",
            "price": "1000",
            "priceCurrencyCode": "KRW",
            "title": "Sample Title",
            "priceAmountMicros": 1000000000
        }
    ]
}
// 실패 시
{
    "error" : {
        "code" : "InvalidUserAccessToken",
        "message" : "Access token is invalid."
    }
}

getPurchases

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial)

https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/{type}

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/{type}

Description

  • Returns a list of unconsumed purchases (including quantity). (Up to 100 items can be queried)

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

type

String

Y

  • The in-app product type code for the purchase request.

  • Refer to Product Type Code

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

Parameter Name
Data Type
Data Size
Required
Description

continuationKey

String

41

N

Next key for purchase history paging

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/inapp
Host: pcapis.onestore.net Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB
 
{
    "continuationKey" : "a2fajklfsjkl2"
}

[ Response ]

Element Name
Data Type
Data Size
Description

productIdList [

-

XVjKVLbw7TIy

String

150

In-app product ID specified during product registration in the developer center

]

purchaseDetailList [

{

orderId

String

40

Payment ID

packageName

String

128

Package name

productId

String

150

In-app product ID specified during product registration in the developer center

purchaseTime

Long

-

Purchase time

acknowledgeState

Int

-

Acknowledge state( 0: Not Acknowledged, 1: Acknowledged)

purchaseState

Int

-

Purchase state

recurringState

Int

-

Automatic payment status

  • 0 : Normal subscription status

  • 1 : Termination reserved status지예약 상태

  • -1 : Not a monthly subscription product

purchaseId

String

20

Purchase ID

purchaseToken

String

20

Purchase token

developerPayload

String

200

An identifier managed by the developer to identify the purchase transaction

quantity

Int

Purchase quantity

}

]

purchaseSignatureList [

String

-

A signature for verifying each purchaseDetailList.

]

continuationKey

String

41

Next key for purchase history paging

Example

// 성공 시
{
    "productIdList": ["다이아100_20170818000000", "루비300_20170818000000"],
    "purchaseDetailList": [
        {
            "orderId": "01239349082349823489342",
            "packageName": "com.onestore.sample",
            "productId": "다이아100_20170818000000",
            "purchaseTime": 1345678900000,
            "acknowledgeState": 1,
            "purchaseState": 0,
            "recurringState": -1,
            "purchaseId": "17070421461015116878",
            "purchaseToken": "17070421461015116878",
            "developerPayload": "E23DEFB029F84F4383ECB0E53B46B6A2",
            "quantity": 1
        },
        {
            "orderId": "01239349082349823489343",
            "packageName": "com.onestore.sample",
            "productId": "루비300_20170818000000",
            "purchaseTime": 1345678920000,
            "acknowledgeState": 0,
            "purchaseState": 0,
            "recurringState": -1,
            "purchaseId": "17070431461610116878",
            "purchaseToken": "17070421461015116878",
            "developerPayload": "T_RPAY_27_201707120110880",
            "quantity": 2
        }
    ],
    "purchaseSignatureList": ["sign1", "sign2"],
    "continuationKey" : "continuationKey"
}
 
// 실패 시
{
    "error" : {
        "code" : "InvalidUserAccessToken",
        "message" : "Access token is invalid."
    }
}

consumePurchase

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume (Development) https://sbpp.onestore.co.kr/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume

Description

  • Changes the state of the purchased managed in-app product to consumed. (Only applicable to consumable products.)

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

purchaseToken

String

Y

Purchase token

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

Parameter Name
Data Type
Data Size
Required
Description

developerPayload

String

200

N

An identifier managed by the developer to identify the purchase transaction

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/inapp/200406083435101108801/consume
Host: http://pcapis.onestore.net
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB

{
"developerPayload" : "1jkl2j3lk1lj"
}

[ Response ]

Element Name
Data Type
Data Size
Description

result

Object

{

code

String

50

Response Code (Successful Processing)

message

String

300

Response Message (Successful Processing)

}

Example

/// 성공 시

{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}



// 실패 시

{
    "error" : {
        "code" : "AlreadyPurchased",
        "message" : "You already have the product or a product that cannot be purchased together."
    }
}

acknowledgePurchase

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/all/{purchaseToken}/acknowledge

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/all/{purchaseToken}/acknowledge

Description

  • Changes the purchased in-app product to the purchase confirmation status. (Supported for both consumable and subscription products.)

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

purchaseToken

String

Y

The purchase token

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

Element Name
Data Type
Data Size
Required
Description

developerPayload

String

200

N

An identifier managed by the developer to identify the purchase transaction

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/inapp/200406083435101108801/acknowledge
Host: pcapis.onestore.net
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB

{
"developerPayload" : "1jkl2j3lk1lj"
}

[ Response ]

Element Name
Data Type
Data Size
Description

result

Object

{

code

String

50

Response Code (Successful Processing))

message

String

300

Response Message (Successful Processing)

}

Example

// 성공 시

{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}



// 실패 시

{
    "error" : {
        "code" : "AlreadyPurchased",
        "message" : "You already have the product or a product that cannot be purchased together."
    }
}

cancelRecurringPurchase

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/auto/{purchaseToken}/cancel

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/auto/{purchaseToken}/cancel

Description

  • Reserve cancellation of the next automatic payment for the monthly subscription (automatic payment) product.

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

purchaseToken

String

Y

Purchase token

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

N/A

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/auto/200406083435101108801/cancel
Host: pcapis.onestore.net
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB

{
}

[ Response ]

Element Name
Data Type
Data Size
Description

result

Object

{

code

String

50

Response Code (Successful Processing)

message

String

300

Response Message (Successful Processing)

}

Example

// 성공 시

{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}



// 실패 시

{
    "error" : {
        "code" : "NoSuchData",
        "message" : "The requested data could not be found."
    }
}

reactivateRecurringPurchase

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/auto/{purchaseToken}/reactivate

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/auto/{purchaseToken}/reactivate

Description

  • Cancel the existing cancellation reservation (termination reservation) for the monthly subscription (automatic payment) product to ensure that the next automatic payment proceeds normally.

  • This API functions correctly only when the status of the requested monthly subscription (automatic payment) product is in the cancellation reservation state.

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

purchaseToken

String

Y

Purchase token

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

N/A

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/auto/200406083435101108801/reactivate
Host: pcapis.onestore.net
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB

{
}

[ Response ]

Element Name
Data Type
Data Size
Description

result

Object

{

code

String

50

Response Code (Successful Processing)

message

String

300

Response Message (Successful Processing)

}

Example

// 성공 시

{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}



// 실패 시

{
    "error" : {
        "code" : "NoSuchData",
        "message" : "The requested data could not be found."
    }
}

cancelSubscription

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/subscription/{purchaseToken}/cancel

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/subscription/{purchaseToken}/cancel

Description

  • Cancel the next automatic payment for the subscription product (cancellation reservation).

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

purchaseToken

String

Y

Purchase token

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

N/A

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/subscription/200406083435101108801/cancel
Host: pcapis.onestore.net
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB
 
{  
}

[ Response ]

Element Name
Data Type
Data Size
Description

result

Object

{

code

String

50

Response Code (Successful Processing)

message

String

300

Response Message (Successful Processing)

}

Example

// 성공 시
{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}
 
 
// 실패 시
{
    "error" : {
        "code" : "NoSuchData",
        "message" : "The requested data could not be found."
    }
}

reactivateSubscription

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/subscription/{purchaseToken}/reactivate

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/subscription/{purchaseToken}/reactivate

Description

  • Cancel the next automatic payment for the subscription product (cancellation reservation).

  • Error Code: Refer to the standard response codes

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

purchaseToken

String

Y

Purchase token

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/subscription/200406083435101108801/reactivate
Host: pcapis.onestore.net 
Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB
 
{
}

[ Response ]

Element Name
Data Type
Data Size
Description

result

Object

{

code

String

50

Response Code (Successful Processing)

message

String

300

Response Message (Successful Processing)

}

Example

// 성공 시
{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    }
}
 
 
// 실패 시
{
    "error" : {
        "code" : "NoSuchData",
        "message" : "The requested data could not be found."
    }
}

getSubscriptionDetail

[ API Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

application/json

Response Format

application/json

Path

(Commercial) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/subscription/{purchaseToken}

(Development) https://sbpp.onestore.net/pc/v7/apps/{clientId}/purchases/subscription/{purchaseToken}

Description

  • Search for detailed information about the subscription.

  • Error Code: Refer to the standard response codes

[ Request ]

Path Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

Client ID of the App Calling the API

purchaseToken

String

Y

Purchase token

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token obtained through the User Access Token issuance API

x-market-code

String

N

Market classification code

  • MKT_ONE: South Korea

  • MKT_GLB: other than South Korea

Body

Example

POST /pc/v7/apps/com.onestorecorp.test/purchases/subscription/200406083435101108801
Host: pcapis.onestore.net Content-Type: application/json
Authorization: Bearer 680b3512-1253-5642-1263-8adjbf651nb
x-market-code: MKT_GLB
 
{
}

[ Response ]

Element Name
Data Type
Description

result {

Object

API Call Result(Normal) - Response in Case of Normal

code

String

Response Code

message

String

Response Message

}

error {

Object

API Call Result(Error) - Response in Case of Error

code

String

Response Code

message

String

Response Message

}

subscription {

Object

productId

String

Custom product ID

productName

String

Product name

parentProductId

String

Parent product ID

parentProductName

String

Parent product name

packageName

String

Package name

productAmount

String

Product amount

productAmountMicros

Long

Product amount x 1M

priceCurrencyCode

String

Currency denomination (e.g., KRW, USD)

imagePath

String

Product image path

periodUnit

String

Usage period unit

period

Integer

Usage period

purchaseToken

String

Purchase token

status

String

Subscription status code Code

startDate

Long

Subscription start time (millis)

expiryDate

Long

Subscription expiration time (millis)

paymentAmount

String

Previous payment amount

paymentAmountMicros

Long

Previous payment amount x 1M

nextPaymentAmount

String

Next payment amount

nextPaymentAmountMicros

Long

Next payment amount x 1M

nextPaymentDate

Long

Next payment time (millis)

pauseAllow

String

Pause availability (Y/N - default)

pauseStartDate

Long

Pause start time (millis) - Only provided if in pause reservation/pause status

pauseEndDate

Long

Pause end time (millis) - Only provided if in pause reservation/pause status

promotionAmount

String

Promotion product amount

promotionAmountMicros

Long

Promotion product amount x 1M

promotionPeriod

Integer

Promotion usage period

priceChanges [

Array

Price change information list

{

priceChangeSeq

Integer

Price change sequence

priceChangeApplyStartDate

Long

Price change effective start time

priceChangePreviousAmount

String

Previous price before price change

priceChangePreviousAmountMicros

Long

Previous price before price change x 1M

priceChangeAmount

String

Price change amount

priceChangeAmountMicros

Long

Price change amount x 1M

priceChangeAgreement

String

Price change agreement

priceChangeAgreementDueDate

Long

Price change agreement expiration time

(Policy supplementary explanation)

  • Value = Price change date + 7 + 30 days

  • Users can agree until the first automatic payment point after the agreement expiration date.

}]

}

Example

// 성공 시
{
    "result" : {
        "code" : "Success",
        "message" : "Request has been completed successfully."
    },
    "subscription" : {
        "productId" : "다이아100_20170818000000",
        "productName" : "다이아100",
        "productAmount" : "2000",
        "productAmountMicros" : 2000000000,
        "priceCurrencyCode" : "KRW",
        "imagePath" : "https://xxx.png",
        "periodUnit" : "MONTH",
        "period" : 1,
        "purchaseToken" : "17070421461015116878",
        "status" : "SUBSCRIBING"
        "parentProductId" : "03904729375",
        "parentProductName" : "모상품명",
        "packageName" : "com.test.game",
        "startDate" : 1345578920000,
        "expiryDate" : 1345678920000,
        "startPaymentDate" : 1345578920000,
        "paymentAmount" : "1000",
        "paymentAmountMicros" : 1000000000,
        "nextPaymentAmount" : "1500",
        "nextPaymentAmountMicros" : 1500000000,
        "nextPaymentDate" : 1345678920000,
        "pauseAllow": "Y",
        "pauseStartDate" : 1625670000000,
        "pauseEndDate" : 1628840000000,
        "promotionAmount" : "1000",
        "promotionAmountMicros" : 1000000000,
        "promotionPeriod" : 1,
        "priceChanges" : [{
            "priceChangeSeq": 1,
            "priceChangeApplyStartDate": 1345678920000,
            "priceChangePreviousAmount" : "2000",
            "priceChangePreviousAmountMicros" : 2000000000,            
            "priceChangeAmount" : "2500",
            "priceChangeAmountMicros" : 2500000000,
            "priceChangeAgreement" : "N",
            "priceChangeAgreementDueDate": 1345678920000
        }]
    }
}
 
 
// 실패 시
{
    "error" : {
        "code" : "NoSuchData",
        "message" : "The requested data could not be found."
    }
}

Payment

Payment Request

Request a ONE Store payment. Pass the paymentParam to the paymentUrl provided in the response of requestPurchase.

Upon success, the ONE Store standard payment screen will be displayed.

[ Call Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

text/plain

Accept

text/plain

URL Path

paymentUrl

Description

Calling the Standard Payment Screen for PC

Parameter

Parameter Name
Data Size
Required
Description

paymentParam

500

M

Payment Request Data (Parameters for invoking the standard payment screen)

Browser Size when Requesting Payment

The optimal browser size for the ONE Store standard payment screen is width=400, height=580.

If the browser is created with a different size than 400 X 580, ONE Store cannot guarantee the correct display and functionality of the payment screen.

Below is an example of calling the ONE Store payment screen in a new browser window.

window.open('paymentUrl','pp01','width=400, height=580, left='+((window.screen.width / 2) - (400 / 2))+', top='+((window.screen.height / 2) - (580 / 2))+' status=no, menubar=no, toolbar=no, sizable=no');

Payment Response

This section delivers the payment results from the standard payment screen to the developer.

[ Call Spec. ]

Signature Algorithm

SHA512 with RSA

Protocol

HTTP/HTTPS

Method

POST

Content-Type

returnUrl : Application/x-www-form-urlencode callbackUrl : Application/json

Accept

callbackUrl : Application/json

SHA512 with RSA

URL Path

returnUrl, callbackUrl

Description

The developer provides the returnUrl (Redirect Page) and callbackUrl (REST API) to deliver the payment results. Both methods use identical Parameter Elements, with returnUrl being submitted in the form data format and callbackUrl being delivered in JSON format.

· However, callbackUrl data is only sent for the final payment result when actual integration with the payment gateway (PG) occurs.

Parameter

Element Name
Data Type
Data Size
Required
Description

responseCode

String

20

Y

Response Code (Refer to the table below)

responseMessage

String

200

N

Empty Value when payment is successful

orderId

String

20

N

Payment ID

purchaseId

String

20

N

Purchase ID

purchaseToken

String

20

N

Purchase token

purchaseTime

Long

13

N

Purchase Time (millis)

developerPayload

String

200

N

An identifier managed by the developer to identify the purchase transaction

quantity

Long

5

N

Quantity for multiple purchases

purchaseSignature

String

2000

N

Signature for purchase information verification

  • For single purchases:

    • (orderId+purchaseId+purchaseToken+purchaseTime+developerPayload)

  • For multiple purchases:

    • (orderId+purchaseId+purchaseToken+purchaseTime+developerPayload+quantity)

billingKey

String

200

N

Billing key for S2S automatic payment approval

Example(returnUrl)

<form name="paymentResultForm" action="{returnUrl}" method="post">

<input type="hidden" name="responseCode" value="Success">
<input type="hidden" name="responseMessage" value="">
<input type="hidden" name="orderId" value="20200429OS01123456789">
<input type="hidden" name="purchaseId" value="20042912345678901234">
<input type="hidden" name="purchaseToken" value="20042912345678905678">
<input type="hidden" name="purchaseTime" value=5615474165165>
<input type="hidden" name="developerPayload" value="pd2020042912354987321">
<input type="hidden" name="quantity" value=3>
<input type="hidden" name="purchaseSignature" value="DB98B5CB92126B1D52E86FED4C6E4AC9E29ADAF356057DB98B5CB92126B1D5......">
<input type="hidden" name="billingKey" value="36FED4C6E4AC9E29ADAF356057DB98B5CB92126B1D52E87577....">

</form>

Example(callbackUrl)

{
  "responseCode" : "Success",
  "responseMessage" : "",
  "orderId" : "20200429OS01123456789",
  "purchaseId" : "20042912345678901234",
  "purchaseToken" : "20042912345678905678",
  "purchaseTime" : 5615474165165,
  "developerPayload" : "pd2020042912354987321",
  "quantity" : 3
  "purchaseSignature" : "DB98B5CB92126B1D52E86FED4C6E4AC9E29ADAF356057DB98B5CB92126B1D5......",
  "billingKey" : "36FED4C6E4AC9E29ADAF356057DB98B5CB92126B1D52E87577...."
}

Response Code

Response Code
Response Message
Description

Success

Empty Value

Payment Success

Fail

Refer to Description

Provides the cause of each PG company and internal system error

UserCancel

Payment has been canceled.

PaymentTimeExpired

Payment time has exceeded

Last updated