웹에서 원스토어 인앱 결제 사용하기

개요

웹 환경에서 원스토어 인앱결제를 이용하기 위한 연동 방법을 설명합니다.

사전 확인

회원인증 연동

윈도우용 게임/앱 또는 PC/Mobile Web 상에서 원스토어 인앱결제를 구현하기 위해서는 회원인증(로그인)연동이 필요합니다. 자세한 사항은 '회원인증'을 참고하시기 바랍니다.

방화벽 정책 등록

CallBackUrl 호출을 위해 원스토어 결제서버와 개발사 서버간 방화벽 정책 등록이 반드시 필요합니다.

CallBackUrl을 사용하실 개발사는 사전에 서버IP 정보를 전달해 주시기 바랍니다. (개발사 서버의 80 혹은 443 포트 연동을 기본으로 하며, 방화벽 정책 등록은 최소 1영업일 이상 소요됩니다.)

연동 아키텍쳐

원스토어는 회원 기반 서비스를 제공합니다. 웹 환경에서 결제 시에도 사용자 회원의 로그인이 필요하며, 로그인 이후 결제 요청이 가능합니다. 결제가 필요한 경우 매번 사용자가 로그인을 수행하지 않도록 OAuth 인증을 지원하며, 모든 구매/결제 관련 서버 API는 로그인 시 제공되는 OAuth Token(이하 User Access Token)을 이용하여 요청해야 합니다.

서버 APIs

원스토어 웹 서버 API는 발급받은 접근 토큰(User Access Token)을 이용하여 호출합니다. HTTP로 호출 시, 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

공통

표준 응답코드

오류응답인 경우 표준 응답코드에 정의된 코드 및 메시지를 전달합니다.

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."
    }
}

상품 타입 코드

Code

Name

Description

inapp

소비성 상품

consume 가능한 소비성 상품

auto

월정액 상품

월 자동결제 상품

subscription

구독형 상품

구독형 상품

all

전체 상품

소멸성 상품 + 월정액 상품 + 구독형 상품

requestPurchase

[API Spec.]

Protocol

HTTPS

Method

POST

Content-Type

application/json

응답 포맷

application/json

Path

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

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

Description

  • 특정 인앱상품의 구매를 요청합니다.

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

type

String

Y

  • 구매를 요청하고자 하는 인앱 상품 타입 코드

  • 상품 타입 코드 참조

productId

String

Y

구매를 요청하고자 하는 인앱상품 ID

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

Body

Element Name
Data Type
Data Size
Required
Description

prchsClientPocCd

String

50

Y

구매 요청 Client 구분 코드 POC_PC : PC 결제 POC_MOBILE : 모바일 결제

returnUrl

String

200

Y

결제결과를 전달받기 위한 redirect URL

callbackUrl

String

200

N

결제결과를 전달받기 위한 REST API URL(최종 결제결과만 전달)

productName

String

50

N

구매를 요청하고자 하는 인앱 상품명, 미 입력시 개발자센터에 등록된 상품명 사용

developerPayload

String

200

N

구매 건을 식별하기 위해 개발사에서 관리하는 식별자

quantity

Integer

N

구매하고자 하는 상품의 수량(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

구매 ID

paymentUrl

String

200

결제 요청 URL 정보

paymentParam

String

-

결제 요청 파라미터 정보

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

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

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

Description

  • 판매 가능한 인앱상품의 상세 정보를 반환합니다.

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

type

String

Y

  • 상품 정보를 조회하고자 하는 인앱 상품 타입 코드

  • 상품 타입 코드 참조

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

Body

Element Name
Data Type
Data Size
Required
Description

productIdList [

String

150

Y

개발자센터에 상품 등록시 지정한 인앱상품 ID

]

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 [

-

상품 상세 정보 목록

{

productId

String

150

구매가능한 상품의 인앱상품 ID

type

String

20

  • 상품 타입

  • 상품 타입 코드 참조

price

String

30

상품금액

priceCurrencyCode

String

10

KRW, USD 등의 통화 구분

title

String

-

상품명

priceAmountMicros

Long

-

상품금액 * 100만

}

]

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

응답 포맷

application/json

Path

(상용)

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

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

Description

  • 소비하지 않은 구매목록(수량포함) 반환합니다. (최대 100건까지 조회)

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

type

String

Y

  • 상품 정보를 조회하고자 하는 인앱 상품 타입 코드

  • 상품 타입 코드 참조

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

Body

Parameter Name
Data Type
Data Size
Required
Description

continuationKey

String

41

N

구매 내역 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

개발자센터에 상품 등록 시 지정한 인앱상품 ID

]

purchaseDetailList [

{

orderId

String

40

결제ID

packageName

String

128

구매한 앱의 패키지명

productId

String

150

개발자센터에 상품 등록 시 지정한 인앱상품 ID

purchaseTime

Long

-

구매 시간

acknowledgeState

Int

-

구매확인 상태( 0: Not Acknowledged, 1: Acknowledged)

purchaseState

Int

-

구매 상태

recurringState

Int

-

자동 결제 상태

  • 0 : 정상가입 상태

  • 1 : 해지예약 상태

  • -1 : 월정액 상품이 아닌 경우

purchaseId

String

20

구매ID

purchaseToken

String

20

구매토큰

developerPayload

String

200

구매건을 식별하기 위해 개발사에서 관리하는 식별자

quantity

Int

구매 수량

}

]

purchaseSignatureList [

String

-

purchaseDetailList 각각의 구매정보 검증을 위한 signature

]

continuationKey

String

41

구매 내역 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

응답 포맷

application/json

Path

(상용) https://pcapis.onestore.net/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume (개발) https://sbpp.onestore.co.kr/pc/v7/apps/{clientId}/purchases/inapp/{purchaseToken}/consume

Description

  • 구매한 관리형 인앱 상품을 소비한 상태로 변경합니다. (소비성 상품만 사용 가능)

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

purchaseToken

String

Y

구매토큰

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

Body

Parameter Name
Data Type
Data Size
Required
Description

developerPayload

String

200

N

구매 건을 식별하기 위해 개발사에서 관리하는 식별자

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

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

응답 포맷

application/json

Path

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

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

Description

  • 구매한 인앱 상품을 구매확인 상태로 변경합니다. (소멸성 상품, 월정액 상품 모두 지원)

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

purchaseToken

String

Y

구매토큰

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

Body

Element Name
Data Type
Data Size
Required
Description

developerPayload

String

200

N

구매 건을 식별하기 위해 개발사에서 관리하는 식별자

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

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

응답 포맷

application/json

Path

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

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

Description

  • 월정액(자동결제) 상품의 다음 자동결제를 취소 예약(해지 예약)합니다.

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

purchaseToken

String

Y

구매토큰

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

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

응답 포맷

application/json

Path

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

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

Description

  • 월정액(자동결제) 상품의 기존 취소 예약(해지 예약)을 취소하여 다음 자동결제가 정상적으로 진행되도록 합니다.

  • 이 API는 요청하는 월정액(자동결제) 상품의 상태가 취소 예약 상태일 때만 정상동작합니다.

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

purchaseToken

String

Y

구매토큰

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

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

응답 포맷

application/json

Path

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

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

Description

  • 구독형 상품의 다음 자동결제를 취소 예약(해지 예약)합니다.

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

purchaseToken

String

Y

구매토큰

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

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

응답 포맷

application/json

Path

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

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

Description

  • 구독형 상품의 다음 자동결제를 취소 예약(해지 예약)을 취소합니다.

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

purchaseToken

String

Y

구매토큰

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

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

응답코드(정상처리)

message

String

300

응답메시지(정상처리)

}

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

응답 포맷

application/json

Path

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

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

Description

  • 구독의 상세정보를 조회한다.

  • 오류 코드 : 표준 응답코드 참조

[ Request ]

Path Parameter

Parameter Name
Data Type
Required
Description

clientId

String

Y

API를 호출하는 앱의 클라이언트 ID

purchaseToken

String

Y

구매토큰

Header

Parameter Name
Data Type
Required
Description

Authorization

String

Y

User Access Token 발급 API를 통해 발급받은 User Access Token

x-market-code

String

N

마켓 구분 코드

  • MKT_ONE: 원스토어 (대한민국)

  • MKT_GLB: 원스토어 (대한민국 외)

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호출 결과(정상) - 정상 시에 응답

code

String

응답코드

message

String

응답메시지

}

error {

Object

API호출 결과(에러) - 에러 시에 응답

code

String

응답코드

message

String

응답메시지

}

subscription {

Object

productId

String

커스텀 상품 ID

productName

String

상품명

parentProductId

String

모상품 ID

parentProductName

String

모상품명

packageName

String

패키지명

productAmount

String

상품 금액

productAmountMicros

Long

상품 금액 * 100만

priceCurrencyCode

String

KRW, USD 등등의 통화 구분

imagePath

String

상품 이미지 경로

periodUnit

String

이용 기간 단위

period

Integer

이용 기간

purchaseToken

String

구매 토큰

status

String

구독 상태 코드

startDate

Long

구독 시작(첫 결제) 일시(millis)

expiryDate

Long

구독 만료 일시(millis)

paymentAmount

String

이전 결제 금액

paymentAmountMicros

Long

이전 결제 금액 * 100만

nextPaymentAmount

String

다음 결제 금액

nextPaymentAmountMicros

Long

다음 결제 금액 * 100만

nextPaymentDate

Long

다음 결제 일시(millis)

pauseAllow

String

일시중지 사용 가능 여부(Y/N(default))

pauseStartDate

Long

일시중지 시작일시(millis) - 일시중지예약/일시중지 상태일 경우에만 응답

pauseEndDate

Long

일시중지 종료일시(millis) - 일시중지예약/일시중지 상태일 경우에만 응답

promotionAmount

String

프로모션 상품 금액

promotionAmountMicros

Long

프로모션 상품 금액 * 100만

promotionPeriod

Integer

프로모션 이용 기간

priceChanges [

Array

가격 변동 정보 목록

{

priceChangeSeq

Integer

가격 변동 시퀀스

priceChangeApplyStartDate

Long

가격 변동 적용 시작 시간

priceChangePreviousAmount

String

가격 변동 이전 금액

priceChangePreviousAmountMicros

Long

가격 변동 이전 금액 * 100만

priceChangeAmount

String

가격 변동 금액

priceChangeAmountMicros

Long

가격 변동 금액 * 100만

priceChangeAgreement

String

가격 변동 동의 여부

priceChangeAgreementDueDate

Long

가격 변동 동의 만료 시간

(정책 부연 설명)

  • Value = 가격변경일 +7+30일

  • 사용자는 동의만료일 이후 첫 자동결제 시점까지 동의가능함.

}]

}

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."
    }
}

결제

결제 요청

원스토어 인 결제를 요청합니다. paymentUrl로 paymentParam을 전달합니다.

성공 시, ONE store 표준 결제화면이 노출됩니다.

[ 호출 Spec. ]

Protocol

HTTPS

Method

POST

Content-Type

text/plain

Accept

text/plain

URL Path

paymentUrl

Description

웹 표준 결제화면 호출

Parameter

Parameter Name
Data Size
Required
Description

paymentParam

500

M

결제요청 데이터 (표준 결제화면 호출을 위한 parameter)

결제 요청 시 브라우저 크기

원스토어 표준 결제화면에 최적화된 브라우저 크기는 width=400, height=580 입니다.

브라우저 크기가 다른 경우 결제화면이 정상적으로 노출되지 않거나 동작하지 않을 수 있습니다.

아래는 새 브라우저 창으로 원스토어 결제화면을 호출할 때의 예입니다. 

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');

결제 응답

표준 결제화면의 결제결과를 개발사로 전달합니다.

[ 호출 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

URL Path

returnUrl, callbackUrl

Description

개발사가 제공한 returnUrl(Redirect Page)와 callbackUrl(REST API)을 통해 결제결과를 전달합니다. 두 방식 모두 Parameter Element는 동일하며 returnUrl은 form data submit 형태로, callbackUrl은 json 형태로 전달됩니다.

  • 단, callbackUrl 데이터는 실제 PG와의 연동 발생시 최종 결제결과에 대해서만 전달됩니다.

Parameter

Element Name
Data Type
Data Size
Required
Description

responseCode

String

20

Y

응답코드 (하단 표 참조)

responseMessage

String

200

N

결제성공(Success)시 빈 값

orderId

String

20

N

결제ID

purchaseId

String

20

N

구매ID

purchaseToken

String

20

N

구매토큰

purchaseTime

Long

13

N

구매시간(millisecond)

developerPayload

String

200

N

구매 건을 식별하기 위해 개발자에서 관리하는 식별자

quantity

Long

5

N

복수구매 수량

purchaseSignature

String

2000

N

구매정보 검증을 위한 signature

  • 단건 결제시

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

  • 복수구매 결제시

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

billingKey

String

200

N

S2S 자동결제 승인을 위한 billing 키

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 Message
Description

Success

빈값

결제성공

Fail

설명참조

각 PG사 및 내부 시스템 오류에 대한 원인을 전달합니다.

UserCancel

결제가 취소 되었습니다.

PaymentTimeExpired

결제시간이 초과 되었습니다.(10분)

Last updated