English
Search
⌃K
Comment on page

Billing_3rd party

What is 3rd Party Payment?

The 3rd party payment is a payment service provided by the seller (hereafter called the “developer”) through direct interworking with Payment Gateway (PG) without the application of ONE store’s in-app payment module (in-app SDK).

How to Apply 3rd Party Payment

  • Transfer Transaction History

    • When 3rd party payment is used, the transaction history of the 3rd party payment (purchase history, cancellation history) must be transferred to ONE store and the development and review of this 3rd party payment service is needed.
    • The transaction history delivered to ONE store will be utilized for ONE store’s ranking and service and as data for settlement between ONE store and the developer.

  • Development & Review Process

​
  • (A) [Developer] Register new app through ONE store Developer Center > Apps > 'Product Registration' button.
    • On the product registration screen, set the '3rd Party Payment method' option to 'Use'.
    • In the 'Agreement to use 3rd Party payment method' pop-up, you have to agree to click 'confirm'.
  • (B) [Developer] You can get OAuth Key (Client secret) issued on the product registration screen.
  • (C) [Developer] Development shall be made with reference to Server API Specification.
    • Issuance of an OAuth Access Token and the transmission of the transaction history, etc. shall be developed.
  • (D) [Developer] The developer is required to confirm that the transaction history has been normally transmitted in the Sandbox environment (https://sbpp.onestore.co.kr).
  • (E) [Developer] To be reviewed by ONE store, the final APK shall be uploaded on ONE store Developer Center and shall interwork with the commercial environment.
    • The commercial environment of the developer must interwork with that (https://apis.onestore.co.kr)of ONE store, and
    • the 3rd party payment gateway company interworking with the developer must interwork with the commercial environment of ONE store.
  • (F) [Developer] A review request shall be made.
  • (G) [ONE store] ONE store is required to make payment in the developer’s app and confirm the transaction history has been normally sent to the commercial environment.
  • (H) [ONE store] ONE store shall request the developer to cancel the 3rd party payment used for review (by sending a request email to the developer’s person in charge).
  • (I) [Developer] The developer shall process the requested cancellation of the transactions used for review.
  • (J) [ONE store] ONE store shall confirm that the history of the cancelled transactions has been sent to the commercial environment, and then complete the review process.
  • (K) [Developer] The developer can process to start the sales of the app for which review has been completed.
Criteria for Transmitting Transaction History
  • The criteria for transmitting the transaction history is as follows:
    • 3rd party payment occurs,
    • when items are directly purchased by using 3rd party payment methods.
    • when the in-app goods* are recharged by using 3rd party payment methods. (*the in-app goods : goods that can be charged only within the app and items can be purchased with this goods only at that app)
    • when items are purchased by using the developer’s own payment methods**. (**the developer’s own payment methods : payment methods that can be purchased by using 3rd party payment methods through other channels such as other apps or web of the same developer and used by multiple apps of the developer)
  • Exceptional cases occur (3rd party payment does not take place),
    • when items are purchased by using the developer’s own promotional payment methods (free coupon, point cash, etc.)
    • Transactions Taking Place in Non-ONE store Supported Countries
  • Transaction history is confirmed based on Purchase ID(developerOrderId).
    • The app using 3rd party payment options is required to offer purchase ID to the user ‘when the 3rd party payment is completed’. (in the payment completion screen and in the email notice)
    • ONE store’s review team shall confirm that the transaction history has been normally sent to ONE store on a basis of the purchase ID when the 3rd party payment /cancellation is made for this app.
  • When sending country codes and currency codes, please note the following:
    • Country codes are transmitted based on ISO_3166-1_alpha-2 for transactions occurring in countries not supported by ONE store.
    • Currency codes are transmitted based on ISO_4217, following the country code. If transactions occur in a currency different from the country's currency, it will be converted to the country's currency for transmission (Google search, as of 00:00 on the same day).
    • In cases where the country code is KR, the x-market-code in the Request Header is sent as MKT_ONE.
    • In cases where the country code is not KR, the x-market-code in the Request Header is sent as MKT_GLB.
  • The transaction amount is sent as the final transaction amount that the customer has paid, including taxes.
    • Once confirmed by the ONE store's review team, if the correct transaction amount is not delivered, the validation rejects or sales suspension may be processed.

Server API

  • What is 3rd Party Payment Server API?

    • When the payment is completed (successful), the developer needs to have a process to send the relevant data to ONE store and synchronize the payment history. In addition, when a change (a cancellation) occurs after the payment and synchronization is completed, it is also required to transmit the history. The purchase/cancellation history of the 3rd party payment that has been transmitted to ONE store will be reflected on ONE store ranking and exposed to general customers and used as data for the settlement with the developer.
    • 3rd party payment server API is an API, which is provided to transfer to ONE store the purchase/cancellation history of the 3rd party payment incurred to the developer.
      • send3rdPartyPurchase (transmits the purchase history of the 3rd party payment)
      • cancel3rdPartyPurchase (cancels the purchase history of the 3rd party payment)
    • OAuth authentication is required first for the interworking of each API, and for the OAuth authentication, client_id and client_secret should be issued in advance.

  • Interworking Environment

    • ONE store API server is provided separately for Sandbox (the development environment) and the commercial environment according to its purpose.
      • Sandbox
      • is a virtual interworking environment to which commercial API standards have been applied as they are.
      • can be used for development review before launching the app on Developer Center once the development for interworking between ONE store and server API has been completed.
      • The payment data transferred from the developer will not be used for ranking or settlement.
      • The commercial environment
      • is a real service interworking environment where the payment history needs to be synchronized for completion or cancellation of the customer’s payment.
      • The data transferred to the commercial environment will be reflected on settlement. If a payment test is performed in the commercial environment, the payment MUST be cancelled.
      • Host information of Sandbox and the commercial environment is as follows.
        Environment
        Service Host
        Sandbox
        Commercial

  • Transmit Purchase History of 3rd Party PaymentInterworking Flow

    • If the user requests a product purchase in an app, the app obtains information necessary for interworking (refer to 4. Reference Code)
    • The purchase request of the user along with the information acquired from the app is sent to the developer’s server.
    • Payment will be processed through 3rd party payment (PG company or in-app payment of other markets) in the developer’s server. The result will be sent to the app.
    • Simultaneously, the purchase history of the 3rd party payment will be transferred to ONE store API Server.
      • (In case ONE store OAuth Access Token expires,) it is required to get an OAuth Access Token issued and then perform API interworking.
      • It is recommended to save the result of the API interworking as a status value. If the interworking is in the failure status, perform retry.
​

ONE store OAuth

Overview

  • For the interworking with Server API related to the transmission of the transaction history of ONE store, it is required to issue an Access Token through OAuth authentication.
  • The Access Token will be valid for 3,600 seconds. When the token expiration time expires or is less than 600 seconds, a new token can be issued by calling getAccessToken().
    • Existing Access Tokens can be used until the end of their expiration
    • Since numerous Access Tokens are issued, different Access Tokens can be obtained and used depending on the developer’s each service instance.
  • The general interworking flow is as follows:
  • The process to get an Access Token (no.1) shall be called when an authentication error occurs at the call of API.
  • To call ONE store Server API, the Authorization Bearer scheme shall be used. A sample of the call is as follows. (Bearer value is the value of Access Token, which has been issued by calling getAccessToken)
POST /v6/purchase/developer/com.onestore.game.goindol/send HTTP/1.1
Host: iap-apis.onestore.net
Authorization: Bearer 680b3621-1234-1234-1234-8adfaef561b4
...

  • getAccessToken (issues an accessToken)

    • Desc: Issue an Access Toke to use Server API.
    • URI: /v6/oauth/token
    • Method: POST, PUT
    • Request Header
      Parameter Name
      Description
      Example
      Content-Type
      When requesting Http, the Content Type must be set to application/x-www-form-urlencoded.
      Content-Type: application/x-www-form-urlencoded
      x-market-code
      Market classification code
      x-market-code: MKT_GLB
      ​
    • Request Body
      Element Name
      Description
      Example
      client_id
      In general, it is the same as the packageName
      com.onestore.game.goindol
      client_secret
      The client secret value, which has been issued at the time of the app registration.
      vxIMAGcVz3DAx20uDBr/IDWNJAPNHFl7YruF4uxB6BI=
      grant_type
      Fixed value
      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
    7
    The result of issuing an Access Token
    client_id
    String
    255
    The OAuth authentication client_id
    access_token
    String
    36
    token_type
    String
    6
    Only the Bearer method is provided.
    expires_in
    Integer
    10
    The token expiration time. The unit is second.
    scope
    String
    1024
    The token use range
    ​
  • Example
    {
    "status":"SUCCESS",
    "client_id":"com.onestore.game.goindol",
    "access_token":"680b3621-1234-1234-1234-8adfaef561b4",
    "token_type":"bearer",
    "expires_in":3010,
    "scope":"DEFAULT"
    }

Server API details

It is the detailed specification for transmitting to ONE store server the purchase/cancellation history of the 3rd party payment.

send3rdPartyPurchase (transfers the purchase history of the 3rd party payment)

  • Desc: The developer transfers the history of the purchase made by using the 3rd party payment method.
  • URI: /v6/purchase/developer/{packageName}/send
  • Method: POST
  • Parameter: String packageName : The package name of an app, which calls API (Data Size: 128).
  • Request Header
    Parameter Name
    Data Type
    Required
    Description
    Authorization
    String
    TRUE
    The access_token issued through the Access Token API
    Content-Type
    String
    TRUE
    application/json
    x-market-code
    String
    FALSE
    Market classification code
    ​
  • 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
    Country codes are transmitted based on ISO_3166-1_alpha-2
    currencyCode
    String
    3
    TRUE
    Currency codes are transmitted based on ISO_4217
    adId
    String
    50
    TRUE
    The ADID obtained from the terminal (if there is no ADID, it will be transferred to UNKNOWN_ADID).
    developerOrderId
    String
    100
    TRUE
    The developer’s purchase ID to identify each purchase case
    (It must be a unique value and error occurs if any duplicate IDs are saved. Refer to Error Response).
    developerProductList
    TRUE
    developerProductId
    String
    150
    TRUE
    The developer’s in-app product ID
    developerProductName
    String
    200
    TRUE
    The developer’s in-app product name
    developerProductPrice
    Double
    10
    TRUE
    The developer’s in-app product price
    developerProductQty
    Integer
    10
    TRUE
    The developer’s in-app product purchase quantity
    simOperator
    String
    20
    TRUE
    The simOperator information obtained from the terminal
    (if there is no simOperator information, it will be transferred to UNKNOWN_SIM_OPERATOR).
    installerPackageName
    String
    150
    TRUE
    The installerPackageName information obtained from the terminal
    (if there is no installerPackageName information, it will be transferred to UNKNOWN_INSTALLER)
    purchaseMethodList
    TRUE
    purchaseMethodCd
    String
    30
    TRUE
    The payment method code (refer to Code Table)
    purchasePrice
    Double
    10
    TRUE
    The amount of payment by each payment method
    totalPrice
    Double
    10
    TRUE
    The total amount of payment
    purchaseTime
    Long
    19
    TRUE
    This is the time when the purchase was made since January 1, 1970. (unit : ms) (9002 error if invalid time is sent. Refer to Error Response.)
    ​
  • Example
    {
    "countryCode": "KR",
    "currencyCode": "KRW",
    "adId": "abcdefgh-abcd-1234-abcd-abcdefgh1234",
    "developerOrderId" : "your_order_id_1234567890",
    "developerProductList" : [
    {"developerProductId" : "your_product_id_1111",
    "developerProductName" : "A",
    "developerProductPrice" : 5000,
    "developerProductQty" : 2
    },
    {"developerProductId" : "your_product_id_2222",
    "developerProductName" : "B",
    "developerProductPrice" : 5000,
    "developerProductQty" : 1
    }
    ],
    "simOperator" : "45005",
    "installerPackageName" : "com.skt.skaf.A000Z00040",
    "purchaseMethodList" : [
    {"purchaseMethodCd" : "TRD_CREDITCARD",
    "purchasePrice" : 10000
    },
    {"purchaseMethodCd" : "TRD_PAYCO",
    "purchasePrice" : 5000
    }
    ],
    "totalPrice" : 15000,
    "purchaseTime" : 1345678920000
    }
  • Response Body
    Element Name
    Data Type
    Data Size
    Required
    Description
    responseCode
    String
    50
    TRUE
    ​
    responseMessage
    String
    500
    TRUE
    ​
    developerOrderId
    String
    100
    TRUE
    The developer’s purchase ID to identify each purchase case
  • Example
    {
    "responseCode": "Success",
    "responseMessage": "Request has been completed successfully.",
    "developerOrderId": "test1695105094231"
    }
    ​
​

  • cancel3rdPartyPurchase (cancels the purchase history of the 3rd party payment)

    • Desc: The developer cancels the history of the purchase made by using the 3rd party payment method.
    • URI: /v6/purchase/developer/{packageName}/cancel
    • Method: POST
    • Parameter: String packageName : the package name of an app, which calls API (Data Size: 128).
    • Request Header
      Parameter Name
      Data Type
      Required
      Description
      Authorization
      String
      TRUE
      The access_token issued through the Access Token API
      Content-Type
      String
      TRUE
      application/json
      x-market-code
      String
      FALSE
      Market classification code
    • 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
      The developer’s purchase ID to identify each purchase case
      (error occurs if any duplicate IDs are saved. Refer to Error Response).
      cancelTime
      Long
      19
      TRUE
      This is the time when the purchase was made since January 1, 1970 (unit: ms)
      cancelCd
      String
      30
      TRUE
      The cancellation reason code (refer to Code Table)
      ​
      ​
    • 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
      ​
      responseMessage
      String
      500
      TRUE
      ​
      developerOrderId
      String
      100
      TRUE
      The developer’s purchase ID to identify each purchase case
    • Example
      {
      "responseCode": "Success",
      "responseMessage": "Request has been completed successfully.",
      "developerOrderId": "test1695105094231"
      }
​

  • Code Table

    • Payment Method Code (purchaseMethodCd)

      • When you use a payment method not defined in the table below, please make an inquiry to Developer Center ([email protected]).
        Payment Method Code (purchaseMethodCd)
        Payment Method Name
        Remarks
        TRD_MOBILEBILLING
        Mobile phone payment
        DCB, mobile phone micro payment
        TRD_CREDITCARD
        Credit card
        Check cards included
        TRD_11PAY
        11pay
        TRD_NAVERPAY
        N pay
        TRD_KAKAOPAY
        Kakao Pay
        TRD_PAYCO
        Payco
        TRD_SAMSUNGPAY
        Samsung Pay
        TRD_SSGPAY
        SSG Pay
        TRD_TOSS
        TOSS
        TRD_BANKTRANSFER
        Account transfer
        Deposit without a bankbook and virtual bank account transfer included.
        TRD_TMONEY
        Mobile T money
        TRD_CASHBEE
        Mobile Cashbee
        TRD_OKCASHBAG
        OK cashbag
        TRD_CULTURELAND
        Culture Cash
        a culture gift certificate
        TRD_HAPPYMONEY
        Happy Money
        Happy Money culture gift certificate
        TRD_BOOKNLIFE
        Book Culture Gift Certificate
        TRD_CASHGATE
        Convenience store cash
        TRD_PAYPAL
        PayPal
        TRD_TMEMBERSHIP
        T Membership
        TRD_KTMEMBERSHIP
        KT Membership
        TRD_LGMEMBERSHIP
        U+ Membership
        TRD_GOOGLEPLAY
        Google Play
        TRD_BITCOIN
        Bit Coin
        TRD_SKINSCASH
        Skins Cash
        TRD_AMAZONPAY
        Amazon Pay
        TRD_PURCHASE_ETC
        Others
  • Cancellation Reason Code (cancelCd)
    carrierCd
    Cancellation Reason Name
    Remarks
    TRD_CANCEL_USER
    Purchase cancellation requested by the user
    TRD_CANCEL_TEST
    Test purchase cancellation
    TRD_CANCEL_ETC
    Others
  • Error Response The server API responds with a JSON-format response when an error occurs in addition to the normal response. Please refer to the following
    • Response Body : JSON format
      Element Name
      Data Type
      Description
      error
      Object
      Error information
      code
      Integer
      Error code
      message
      String
      Error message
      ​
    • 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.
    PayMethodPriceSumNotMatch
    결제총액과 결제수단 별 결제금액의 합이 일치하지 않습니다.
    The total amount of payment and the sum of the amount of each payment method do not match.
    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

  • This guide includes client development content to support the transfer of the transaction history of the apps, which are sold on ONE store by using 3rd party payment options.
  • The developer can check the contents provided as below and directly implement the functions, or use the contents with reference to the sample code.
​

Obtain App Installer Information

  • The application installed on ONE store will have a total of 8 install package information (Including Samsung Galaxy Store. See the chart below)
  • If the installer, which enables the app to be installed on ONE store with the following code, is ONE store, the payment information of such app should be transferred to ONE store along with the install package name.
  • If it is not possible to check whether there is an installer, "UNKNOWN_INSTALLER" will be sent.
    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
    *
    * Samsung Galaxy Apps : com.sec.android.app.samsungapps
    *
    * If you read null string, return the "UNKNOWN_INSTALLER".
    *
    * @param context application context
    * @return Name of installer package name or "UNKNOWN_INSTALLER"
    */
    public static String getInstallerPackageName(@NonNull Context context) {
    if (context != null) {
    ​
    Context applicationContext = context.getApplicationContext();
    PackageManager pm = applicationContext.getPackageManager();
    final String installPackageName =
    pm.getInstallerPackageName(applicationContext.getPackageName());
    ​
    if (!TextUtils.isEmpty(installPackageName)) {
    return installPackageName;
    }
    }
    return "UNKNOWN_INSTALLER";
    }
​
#
Installer
Installer Package Name
1
ONE store SKT
com.skt.skaf.A000Z00040
2
ONE store KT
com.kt.olleh.storefront
3
ONE store LG U+
com.lguplus.appstore
4
ONE store GLOBAL
com.onestorecorp.gaa.storeapp

Others

3rd Payment Settlement Process (Global)

  • 3rd Payment Tax Policy
    • If developers sell products through 3rd party payments, they are responsible for paying value-added tax (VAT) and other related taxes in the respective countries. This means that developers should directly pay VAT and related taxes in each country.
  • 3rd Party Payment Service Fees
    • Service fees are calculated after deducting VAT from the final consumer payment amount.
    • Even if transactions occur in multiple countries through 3rd party payments, the service fees are aggregated and should be transferred to a virtual account by the 25th of each month.
      • Sellers located in Korea: in KRW
      • Sellers located outside of Korea: in USD
    • "Check the virtual account at: Developer Center > Settlement > 3rd party Payment > Settlement Status (at the bottom) "
  • Fee Document
    • Sellers located in Korea: Issued with one tax invoice (sum of fees from sales in ONE store Korea and Global).
      • However, in the case of sales in Korea, as it is a joint venture, seperate fee documents will be issued by ONE store, KT, and LG U+.
    • Sellers located outside Korea: Issued with one invoice (sum of fees from sales in ONE store Korea and Global).
    • Path: Developer Center > Settlement > 3rd party payment > Settlement Status > Tax Invoice / INVOICE
  • Editing Document Information
    • If you need to edit member information on the tax invoice(Invoice), please request it from the Developer Center ([email protected]) by the end of the sales month.
  • Unpaid Fees
    • If fees remain unpaid, services may be restricted, including the discontinuation of product sales, in accordance with the sales agreement.

Technical / Policy Inquiry