Galaxy Store 유저의 구매 완료 데이터를 빌링에 저장 요청 - 게임에서 결제 기능을 직접 구현한 경우
기본 정보
협의된 특정 게임은 자체 구현한 결제를 사용할 수 있습니다.
단, 결제 어뷰징 방지는 게임쪽에서 잘 구현해주셔야합니다.
예) 저렴한 상품 구매 후 비싼 상품 지급 요청 방지
게임에서 결제를 구현했지만 매출 인식과 같은 재무 처리 및 플랫폼 기능을 일부 활용하기 위해서 ‘구매 완료 데이터’를 전송해줄 필요가 있습니다.
Samsung IAP Server API의 Verify a Purchase 결과 데이터를 수집합니다. 게임 서버에서는 해당 API로 검증 후 status가 success인 결제 완료 데이터를 전송해주시면 됩니다.
빌링 서버에서 해당 API로 재 검증은 지원하지 않습니다.
Request
HTTP Request end point
POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/galaxy/store/implement/self/completed/save
HTTP Request Header
아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
X-Req-Pjid
프로젝트ID
기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key
인증용 키
기술 PM 등에게 전달받은 해당 게임용 인증 키
HTTP Request Parameter
Content-Type: application/json 으로 요청되어야 합니다.
영수증 관련 정보들의 길이 및 escape 등의 문제 때문
key 1
key 2
데이터 타입
필수
설명
예
pjid
String(20)
Y
프로젝트ID
동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음
1004
playerId
String(50)
Y
주문 완료를 진행하는 유저ID
ipCountry
String(10)
N
player의 IP기반 국가코드로 법적 대응을 위해서 수집
3166-1 alpha-2 국가코드
AWS CloudFront를 사용한다면 HTTP헤더의 CloudFront-Viewer-Country에서 쉽게 얻을 수 있음
productId
String(200)
Y
구매를 진행한 상품ID(SKU와 같은 값)
galaxy_gamecode_ruby01
참고) 스토어구분코드_게임구분자_게임에서정의한상품ID
microPrice
long
Y
구매 금액 micro단위
사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용
구매 금액 micro단위(예. $0.99는 990,000 µ$. 100만을 곱함)
memo
String(2000)
N
메모
필요시 옵셔널하게 사용
galaxyPurchaseId
String(100)
Y
Unique identifier of the in-app item purchase transaction
갤럭시스토어에 verify 요청한 purchaseID
7efef23271b0a48746a9d7c391e367c7a802980d391d7f9b75010e8138c66c36
galaxyVerifyPurchaseResult
json array
Y
갤럭시 스토어 Verify a purchase 결과 json
status가 success인 경우
packageName
String(200)
Y
Package name of the app with a completed transaction
com.samsung.android.test
orderId
String(50)
Y
Unique identifier assigned to the purchase receipt
빌링 시스템에서 중요 키로 사용 됨
S20191129KRA1908197
mode
String(20)
Y
IAP operating mode in effect at the time of purchase
참고: TEST인 경우 빌링 시스템에서도 테스트 결제로 처리 됨
TEST 또는 RODUCTION
status
String(20)
Y
Processing result of the request for the receip
success
purchaseDate
String
Y
Date and time of the item purchase and payment transaction.
GMT기준의 YYYY-MM-DD HH:mm:ss 포맷
2019-11-29 01:32:41
currencyCode
String(5)
Y
Currency code (3 characters) of the purchaser's local currency. (for example, EUR, GBP, USD)
KRW
currencyUnit
String(3)
Y
Symbol of the purchaser's local currency (for example, €, £, or $)
₩
paymentAmount
String
Y
Total amount, including the in-app item price and all applicable taxes, billed to the user
100.000
paymentId
String(50)
Y
Unique identifier assigned to the in-app item payment transaction when it was successful
20191129013006730832TRAN
itemId
String(200)
Y
Unique identifier of the in-app item registered in Seller Portal
galaxy_com.hybeim.test_gem_01
itemName
String(200)
Y
Title of the in-app item registered in Seller Portal
Test Pack
itemDesc
String(2000)
N
Brief explanation of the in-app item registered in Seller Portal
IAP Test Item. Best value!
paymentMethod
String(50)
Y
Type of payment option used to purchase the item
Credit Card
consumeYN
String(1)
Y
For consumable in-app items only, whether or not the item has been reported as consumed and is available for purchase again
Y 또는 N
consumeDate
String
Y
Date and time the consumable item was reported as consumed.
GMT기준의 YYYY-MM-DD HH:mm:ss 포맷
2019-11-28 10:18:11
consumeDeviceModel
String(50)
N
Model name of device that reported the item as consumed
SM-G965F
passThroughParam
String(50)
N
Transaction ID created by your app for security. Returned only if the pass-through parameter was set.
TEST_PASS_THROUGH
HTTP Request Parameter(Sample json)
요청 샘플 json입니다. 하단 curl 커맨드를 참고하셔도 좋습니다.
{ "playerId": "playerId", "ipCountry": "KR", "productId": "galaxy_gamecode_ruby01", "microPrice": 100000000, "currency": "KRW", "memo": "테스트 메모", "pjid": "1201", "galaxyPurchaseId": "7efef23271b0a48746a9d7c391e367c7a802980d391d7f9b75010e8138c66c36", "galaxyVerifyPurchaseResult": { "packageName": "com.samsung.android.test", "orderId": "S20191129KRA1908197", "mode": "PRODUCTION", "status": "success", "purchaseDate": "2019-11-29 01:32:41", "currencyUnit": "₩", "currencyCode": "KRW", "paymentAmount": "100.0", "paymentId": "20191129013006730832TRAN", "itemId": "57515", "itemName": "Test Pack", "itemDesc": "IAP Test Item. Best value!", "paymentMethod": "Credit Card", "consumeYN": "Y", "consumeDate": "2019-11-28 10:18:11", "consumeDeviceModel": "SM-G965F", "passThroughParam": "TEST_PASS_THROUGH" } }
Response
응답은 JSON형태로 전달됩니다.
Success sample
성공할 경우 빌링 시스템에는 구매 완료 데이터가 생성되며 이때 boid가 생성됩니다.
아래는 성공의 경우 샘플 json입니다.
{
"resultCode": "SUCCESS",
"resultMessage": "Saving the purchase completion data was successful. The boid generated by the billing system is '417'"
}
Error sample
이미 전송 완료된 데이터를 다시 요청한 경우
{
"resultCode": "INVALID_PARAMETER",
"resultMessage": "Exist billing paymentOrderId:'S20191129KRA1908197'(boid:'417'). Check your params's Galaxy Store 'orderId'",
"traceId": "b_94c45ca494a4"
}
에러 코드 정의
아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
SYSTEM_ERROR
빌링 API에서 발생한 시스템 에러
HTTP 상태코드 500 리턴
NOT_ALLOW_AUTH
API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
INVALID_PARAMETER
요청 curl 샘플
도메인 및 인증 헤더 등은 변경 필요
curl -X 'POST' \
'http://localhost:10001/billing/api-game/v1/purchase/galaxy/store/implement/self/completed/save' \
-H 'accept: application/json;charset=UTF-8' \
-H 'X-Req-Pjid: TODO' \
-H 'X-Auth-Access-Key: TODO' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"playerId": "playerId",
"ipCountry": "KR",
"productId": "galaxy_gamecode_ruby01",
"microPrice": 100000000,
"currency": "KRW",
"memo": "테스트 메모",
"pjid": "1201",
"galaxyPurchaseId": "7efef23271b0a48746a9d7c391e367c7a802980d391d7f9b75010e8138c66c36",
"galaxyVerifyPurchaseResult": {
"packageName": "com.samsung.android.test",
"orderId": "S20191129KRA1908197",
"mode": "PRODUCTION",
"status": "success",
"purchaseDate": "2019-11-29 01:32:41",
"currencyUnit": "₩",
"currencyCode": "KRW",
"paymentAmount": "100.0",
"paymentId": "20191129013006730832TRAN",
"itemId": "57515",
"itemName": "Test Pack",
"itemDesc": "IAP Test Item. Best value!",
"paymentMethod": "Credit Card",
"consumeYN": "Y",
"consumeDate": "2019-11-28 10:18:11",
"consumeDeviceModel": "SM-G965F",
"passThroughParam": "TEST_PASS_THROUGH"
}
}'
Last updated