Galaxy Store 유저의 구매 완료 데이터를 빌링에 저장 요청 - 게임에서 결제 기능을 직접 구현한 경우

해당 API는 게임에서 결제를 직접 구현한 경우에 구매 완료 데이터를 빌링 시스템에 전송하는 API입니다.

기본 정보

1. 협의된 특정 게임은 자체 구현한 결제를 사용할 수 있습니다.

   1. 단, 결제 어뷰징 방지는 게임쪽에서 잘 구현해주셔야합니다.

      1. 예) 저렴한 상품 구매 후 비싼 상품 지급 요청 방지

2. 게임에서 결제를 구현했지만 매출 인식과 같은 재무 처리 및 플랫폼 기능을 일부 활용하기 위해서 ‘구매 완료 데이터’를 전송해줄 필요가 있습니다.

   1. Samsung IAP Server API의 Verify a Purchase 결과 데이터를 수집합니다. 게임 서버에서는 해당 API로 검증 후 status가 success인 결제 완료 데이터를 전송해주시면 됩니다.

   2. 빌링 서버에서 해당 API로 재 검증은 지원하지 않습니다.

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증방식	HTTP 헤더 인증 정보
HTTP 메소드	POST
Content-Type	application/json

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만을 곱함)
currency		String(10)	Y	구매 금액의 화폐 단위 3글자 포맷의 ISO-4217	USD
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"
  }
}'