< 참고 >

본 문서는 원스토어 인앱 SDK v16(API v4)에 대한 가이드 문서입니다. 최신 원스토어 인앱 SDK v17(API v5)에 대한 가이드 문서는 원스토어 개발자센터에서 제공되고 있습니다.

최신 인앱 SDK v17 가이드 문서 링크 : https://dev.onestore.co.kr/devpoc/reference/view/IAP_v17

• 원스토어에서 제공하는 결제 모듈(안드로이드 SDK)과 Server API 연동을 위한 전반의 내용을 간략히 연동 개발사의 관점에서 작성하였다.
• 본 문서에서 가이드하는 연동 상의 Business Flow는 원스토어에서 권장하는 방식이며 개발사의 시스템 특성에 따라 적절히 변경 적용 개발이 가능하다.
• 각 기능별 세부 내용은 원스토어 개발자 센터의 공식 가이드를 통하여 확인이 가능하다.

• IAP(In-App Purchase, 인앱결제): 부분유료화 인앱 상품 결제
• 개발사(Merchant): 원스토어에서 제공하는 결제 모듈을 연동하여 결제서비스를 제공하는 업체
• 인앱상품(Product ID, 이하 PID) : 개발사에서 배포하는 앱 내부에서 판매하는 개별 상품, 해당 상품은 원스토어에서 제공하는 상품 ID에 1:1로 대응됨
• IAP SDK(이하 SDK): 안드로이드 단말의 결제 서비스 연동을 위한 library로 .jar 파일 형태로 제공
• IapPlugin: IAP SDK와 동일
• 결제 Transaction : 개별 결제건에 대한 세부 내용과 진행 흐름 전반을 의미
• TXID : 결제 완료시 SDK에서 응답(response)값으로 전달되는 값으로, 원스토어에서 발행하는 결제건에 고유로 부여되는 ID (Payment Transaction ID)
• TID : TXID와 별개로 개별 결제건에 대해서 개발사가 직접 부여할 수 있는 고유ID
• 전자영수증 : 결제 완료시 SDK에서 TXID와 함께 응답값으로 전달되는 값으로, 결제 세부 내용에 대한 전자서명값

• 인앱상품의 유형에 따라 결제시 중복 구매 불가 및 구매 가능 시간이 관리됨

• 결제가 정상 완료된 상품에 대한 ‘사용완료’ 혹은 ‘소비’의 개념은 없음
• 개발사의 앱 서버(Billing)에서 판매된 상품의 사용 가능 여부의 이력 관리 필요

• 결제에 대한 완료여부를 단말(SDK의 응답)을 통해서만 알 수 있음

• 결제 완료 후 SDK의 응답값 중 저장이 필요한 값은 개발사에서 저장 관리 필요
• 향후 개별 결제건에 대한 Server to Server Notification 제공 예정

• 개발자센터 개발사 계정 생성
• 앱 및 상품 정보 설정 및 생성
• 테스트 환경에서 SDK 연동 개발
• 앱 검증요청 및 상품 판매상태 전환

• Live 모드(SDK의 Release모드)상에서는 원스토어의 상품 결제 검증이 완료된 상태에서만 정상 결제가 가능함

• SDK를 실제 단말App에 연동하여 결제 기능 개발
• SDK에서 제공하는 각종 Command API 를 호출하여 정상 응답 확인
• 원스토어에서 제공하는 Server to Server API를 호출하여 정상 응답 확인

• 안드로이드 단말상 연동을 위한 초기 환경 설정 및 전반의 내용은 아래의 링크를 참조

• IAP Developer Guide

• 결제 처리 Flow

• 아래 그림상 IapPlugin이 SDK에 해당되며, 단말에 설치되는 App이 YourApp 에 해당됨
• 그림상 결제 요청과 응답시의 Parameter는 필수 인자만 표시함
• SDK로 부터 정상 응답을 받은 경우 일부값(3번 항목, 최소 권고사항)을 아래와 같이 App의 Server로 전송하여 처리필요

[그림1] SDK 결제 요청 처리

• 결제 요청시 (SDK 에서 제공하는) IapPlugin.sendPaymentRequest API를 호출

• 상세참고 : sendPaymentRequest
• 요청 Parameter별 분석

• 결제에 대한 응답은 (SDK에서 제공하는) requestCallback 오브젝트를 전달 받음

• 응답 형태 (실제 개발시class object의 형태임)

{
   "api_version" : "(api version)", 
   "identifier" : "(request id)", 
   "method" : "purchase", 
   "result" : {
"code" : "(result code)",
"message" : "(result message)",
"txid" : "(id)",
"receipt" : "(encode receipt using Base64)", 
"count" : "(count of product)",
"product" : [ { "(product information)" } ]
   }
}

• 주요 응답 Parameter별 분석

• 응답코드값 참고 : AP Reference Result Code

• 실질적 결제 처리 흐름

• [그림1]의 흐름과 비교하여 개발사의 App에서 구매요청 발생시 SDK의 결제 API의 호출이 아닌 개발사의 서버(YourServer)에 사용자의 결제 요청 내용을 전송
• 개발사의 서버에서는 User가 요청한 상품의 구매가능 여부, User 계정 상태 등을 확인하여 개발사 자체적인 구매 Transaction을 생성

[그림2] 실질적 결제 요청 흐름

• 구매 Transaction의 내용은 아래의 값 들로 구성될 수 있음(개발사DB에서 저장 관리 필요)

• TID : 개발사에서 발행하는 unique한 구매 ID
• User(Payer) ID : 개발사에서 관리하는 사용자 ID
• 상품 ID : pId나 혹은 개발사에서 관리하는 상품 ID
• 기타 : 판매시 일시적으로 설정된 상품명이나 가격

• 주의사항

• 결제 진행중 단말 자체의 문제(리소스 부족, 네트워크 이슈 등)로 결제 결과를 SDK로 부터 전달 받지 못하는 상황이 발생할 수 있음

• 선택적으로 SDK의 구매이력 조회, Server API인 TID 구매이력 조회 등을 활용하여 상품 활성화(지급, 배송)를 위한 복구 로직의 개발이 요구됨

• 상품ID(PID) 별로 환경에 따라 판매가능 상태가 별도로 관리되어, 상용환경에서 판매가능 상태가 아닌경우 결제가 제한됨

• SDK는 결제와 관련된 추가 API를 제공하며, 앱(단말)상에서도 SDK의 API를 이용하여 최종의 결제 상태를 조회할 수 있음
• 관련 링크

• 제공 API 형식 : sendCommandRequest
• 구매이력 API : request_purchase_history

• 권고 Flow

• 결제 진행중 사용자 단말의 비정상적 종료로 결제 결과(response)를 받지 못한 경우 사용자 단말의 App에 아이템 미지급(비활성화) 상태가 발생 가능
• 앱 종료후 재시작 시점에 (SDK에서 제공하는) IapPlugin.sendCommandPurchaseHistory API를 호출하여 상품ID별 구매이력 취득후, 개발사의 Billing 서버의 구매 이력과 비교하여 미지급 상품에 대한 지급 보정 가능

[그림3] 단말(SDK)를 통한 결제 이력 조회

• 요청 Parameter

• AppID를 기준으로 전체 구매 이력 조회 가능 (개별 상품별로도 조회가능)

{
    "method" : "request_purchase_history",
    "param" : {
        "appid" : "OA12345678"
    } 
}

• 응답 Parameter

• 구매가 발생하였던 상품의 리스트를 확인할 수 있으며, validity값을 활용하여 중복 구매여부 및 사용 상태로 활용이 가능하다. (IapPlugin.change_product_properties를 통하여 validity 값의 차감 가능)

{
    "api_version" : "4",
    "identifier" : "1234567890",
    "result" : {
        "code" : "0000",
        "message" : "요청이 성공적으로 처리되었습니다.", 
        "count" : 2,
        "product" : [ {
            "id" : "0000000020",
            "name": "2011 프로야구 아이템 1000원", 
            "type": "one-time",
            "kind": "consumable",
            "validity": 0,
            "price": 1100,
            "startDate": "20121201173841",
            "endDate": "20121201173841",
            "status": {
                "code" : "PH02", 
                "message": "사용 기간이 만료되었습니다. 계속 이용을 원하시는 경우 재구매가 필요합니다."
            }
        },{
            "id" : "0000000021",
            "name": "자동 결제 상품",
            "type": "auto-renewal-month ",
            "validity": 365,
            "price": 1100,
            "startDate": "20151201173841",
            "endDate": "20151231235959",
            "status": {
                "code" : "PH00", 
                "message": "아이템 인증에 성공하였습니다."
            } 
        }]
    }
}

• 주의사항

• 초기 구동 시점(loading)이 아닌 앱의 진행 상태(예시: 게임상 월드변경, 인벤토리 진입 등)에 해당API를 반복적으로 호출하는 로직은 권고하지 않음

지금까지 안드로이드 SDK 연동에 대해서 살펴보았고, 다음 부분은 원스토어에서 제공하고 있는 서버 API에 대한 내용이다. 서버 API의 연동 여부는 개발사의 선택사항으로 연동하지 않아도 결제 진행에는 영향을 주지 않으나 서비스 운영의 효율을 높이는 측면에서 연동을 권장한다.

• 전자영수증은 개별 결제건에 대한 세부 내용의 전자서명(Digital Signature)값으로, 결제 transaction 자체의 변조 여부 확인이 가능하여 부정상적 결제 여부의 판별 가능
• 해당 기능은 SDK와 Server 양측에서 동일 기능의 API를 제공하지만 보안 및 운영성 측면에서 Server API의 연동을 권장함
• 상세참고 : 전자 영수증 검증 API
• 권고 Flow

• 1)결제가 정상적으로 완료된 경우, 단말(SDK)로 부터 전자영수증(receipt)이 앱으로 전달되고, 앱은 해당 데이터를 앱의 서버로 전달
• 2~3)앱서버는 원스토어의 전자영수증 검증 API를 통하여, 달말로 부터 전달받은 전자영수증 데이터의 이상여부를 검증
• 3~4)전자영수증 검증결과가 이상이 없을 경우(status=0), 아이템 지급 처리

[그림4] 전자영수증 검증 흐름

• 주요 요청 Parameter 분석

• HTTP/JSON 형태로 원스토어의 결제 서비스 서버에 아래와 같이 전송

{
    "txid":"TSTORE0004_20150515102510XXXXXXXXXXXXXXX",
    "appid":"OA00012345",
    "signdata":”MIIH7QYJKoZIhvcNAQcCo … ozANBglghkgBZQMEA" 
} 

• signdata 값은 결제 완료후 SDK로 부터 응답받는 전자영수증 값으로 결제 완료 직후 위의 API로 검증이 진행되어야 하며 이후 반복적인 호출은 권장하지 않음

• 주요 응답 Parameter 분석

• HTTP/JSON 형태로 응답은 아래의 형태

{
    "status" : 0,
    "detail" : "0000",
    "message" : "정상검증완료", 
    "count" : 1,
    "product" : [{
        "log_time" : "20120321154451", 
        "appid" : "OA12345678", 
        "product_id" : "0900012345", 
        "charge_amount" : 1000,
        "tid" : "201012226_01047637315_00000239",
        "detail_pname" : "커스텀 상품명",
        "bp_info" : "X"}]
}

• status=0 and detail=”0000”인 경우 전자영수증 데이터 자체에 변조가 없음을 의미하며, 개발사가 인지하고 있는 상품가격, tid, product_id 등의 정보를 비교하여 응답값에 문제가 없는지 비교 필요(권고)

• 주의사항

• 전자영수증은 개별 결제에 대해서 발행되는 고유의 전자서명값으로 결제 자체의 위변조 여부를 확인하는 용도로 사용될 수 있음
• 성공한 결제인 경우에만 전자영수증이 발행되며, 해당 결제건의 가장 최근의 상태를 확인하는 용도로는 사용할 수 없음

• TID는 결제 발생시 개발사에서 발행하는 구매(결제) ID로 원스토어 결제 시작 이전 시점에 생성되며 개발사에서 해당값을 인지하고 있다는 점에서, 결제가 성공적으로 완료된 이후에 전달 받을 수 있는 전자영수증(원스토어가 발행)과는 다름

• 결제완료 시점 혹은 결제 여부 완료 여부를 알 수 없는 시점에 TID구매이력 조회 API를 호출하여 결제의 성공여부를 확인할 수 있음 (결제 이후 환불 등 변동 내역은 확인 불가)

• 참고 링크 : TID 구매이력 조회 API

• 권장 Flow

• 권장하는 결제상의 호출 시점은 결제 완료 직후로 전자영수증 검증과 동일(그림4 참고)
• 단말상의 결제 결과를 전달 받지 못하여 최종 결제의 상태를 개발사의 앱이나 서버에서 알 수 없는 경우 아래와 같이 batch 를 통한 상태 조회 및 동기화가 가능

[그림5] TID 구매이력 조회

• 사용자의 단말 혹은 앱이 비정상적으로 종료되고 일정시간 경과후 재기동 되는 시점에 결제 상품의 정보를 앱서버로 부터 전달받아 구매건의 복원이 가능

• 주의 사항

• 해당 API는 결제가 완료된 시점, 혹은 결제 결과를 알 수 없는 상황에 최소한의 호출을 권고
• APP 최초로딩 시점, 상점 진입 시점, 사용자 변경 시점 등 APP의 내용 흐름에 종속적인 경우 트래픽 과부하 및 서비스 장애 요인으로 작용 가능
• 전자영수증 검증과는 용도가 같기 때문에 중복적 사용은 권장하지 않음

• 아래 [그림6]는 원스토어 IAP 결제 연동시의 전체 권장 Flow로 결제 완료(5)이후 전자영수증 검증은 선택적 사항으로 개발사에서 연동 여부를 결정
• 단말결제 진행 과정상(3-4)에서의 문제로 결제 결과를 전달 받지 못한 경우, TID구매이력 조회를 통하여 결제 상태의 복원이 가능

• TID 구매이력 조회는 batch 나 개발사 CS 시스템을 통한 조작으로 결제 이력의 복원이 이루어지도록 구현을 고려해 볼 수 있음

[그림6] 권장 결제 흐름

• 결제 진행상 오류로 결제를 한 사용자가 아이템을 지급 받지 못한 경우에 대한 대응으로 위의 TID 구매이력 조회뿐만 아니라 SDK에서 제공하는 구매이력 조회 API (IapPlugin.request_purchase_history)를 활용하여 아이템 미지급건의 복원 로직도 고려해 볼 수 있음

• 상세 내용은 [SDK : 주문 조회 등 API 연동] 파트 참고