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

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

기본 정보

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

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

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

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

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

Request

HTTP Request end point

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/google/play/implement/self/consumable/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 등의 문제 때문

이름	데이터 타입	필수 Y/N	설명	예
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에서 쉽게 얻을 수 있음
testerPurchaseYn	String(1)	Y	구글 테스터로 등록되어 결제가 진행된 테스트 결제 여부 참고: 결제 검증 과정에서 테스터 결제인지 확인 가능	Y 또는 N
productId	String(200)	Y	구매를 진행한 상품ID(SKU와 같은 값)	google_play_gem_01
microPrice	long	Y	구매 금액 micro단위 사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용	구매 금액 micro단위(예. $0.99는 990,000 µ$. 100만을 곱함)
currency	String(10)	Y	구매 금액의 화폐 단위 3글자 포맷의 ISO-4217	USD
purchaseOriginalJson	String	Y	구매 원본 Json 앱에서 구현시 참고 링크 base64 디코딩된 receiptData	{"orderId":"GPA.3339-8889-4444-64541","packageName":"com.hybeim.블라블라","productId":"google_com.hybeim.블라블라_gem55000\ .... 블라블라
purchaseSignature	String	Y	구매 Signature 앱에서 구현시 참고 링크
memo	String(2000)	N	메모 필요시 옵셔널하게 사용

Response

응답은 JSON형태로 전달됩니다.

Success sample

• 성공할 경우 빌링 시스템에는 구매 완료 데이터가 생성되며 이때 boid가 생성됩니다.

• 아래는 성공의 경우 샘플 json입니다.

{
  "resultCode": "SUCCESS",
  "resultMessage": "Saving the purchase completion data was successful. The boid generated by the billing system is '319716'"
}

Error sample

• 이미 전송 완료된 데이터를 다시 요청한 경우

{
  "resultCode": "INVALID_PARAMETER",
  "resultMessage": "Exist paymentOrderId data:'GPA.3340-4508-1960-80934'. Check your purchaseOriginalJson -> orderId",
  "traceId": "b_ba6591e1fec9"
}

• 변조된 영수증 데이터(purchaseOriginalJson) 또는 잘못된 purchaseSignature로 요청

{
  "resultCode": "NOT_VALID_RECEIPT",
  "resultMessage": "The check for alteration of the receipt(purchaseOriginalJson) failed(not valid). playerId:'playerId' | purchaseOriginalJson:'{\"orderId\":\"GPA.3340-4508-1960-80934\",\"packageName\":\"com.hybeim.astra\",\"productId\":\"google_com.hybeim.astra_package0048\",\"purchaseTime\":1721785502338,\"purchaseState\":0,\"purchaseToken\":\"gpkdmcfofhllhlaonkpaiknc.AO-J1OwtKjJImbJ0mL5g2x2SsMcDKG4a2_-kIzycxNt124R5nkwhPWIbWEUTDz8EYyMrLH9uQfZhXqmPGRo6djlF_5azqwNg3w\",\"quantity\":1,\"acknowledged\":false}'",
  "traceId": "b_d8906f6938f3"
}

에러 코드 정의

• 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다. (참고 링크)
• 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.

  • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.

  • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.

에러코드	비고
SYSTEM_ERROR	빌링 API에서 발생한 시스템 에러 HTTP 상태코드 500 리턴
NOT_ALLOW_AUTH	API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생

• 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.

에러코드	비고
INVALID_PARAMETER
NOT_VALID_RECEIPT	구매 영수증 검증 영수증 변조 등 잘못된 영수증 문제

요청 curl 샘플

• 도메인 및 인증 헤더 등은 변경 필요

curl -X 'POST' \
  'http://localhost:10001/billing/api-game/v1/purchase/google/play/implement/self/consumable/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 '{
  "pjid": "1201",
  "playerId": "playerId",
  "ipCountry": "KR",
  "testerPurchaseYn": "Y",
  "productId": "google_com.hybeim.astra_package0048",
  "microPrice": 990000,
  "currency": "KRW",
  "purchaseOriginalJson": "{\"orderId\":\"GPA.3340-4508-1960-80934\",\"packageName\":\"com.hybeim.astra\",\"productId\":\"google_com.hybeim.astra_package0048\",\"purchaseTime\":1721785502338,\"purchaseState\":0,\"purchaseToken\":\"gpkdmcfofhllhlaonkpaiknc.AO-J1OwtKjJImbJ0mL5g2x2SsMcDKG4a2_-kIzycxNt124R5nkwhPWIbWEUTDz8EYyMrLH9uQfZhXqmPGRo6djlF_5azqwNg3w\",\"quantity\":1,\"acknowledged\":false}",
  "purchaseSignature": "W1aDfkIdY7dWtKN4U9RM6ZmYsX3LCmXUfZcYbWPkb/bB63xBjtVl02jztzhXl81fIeCHIjWkeI+g+j/3E8MxepBGHLtAs5Utsh3/i4SKL5cG7Qz0zoba8SkgLqR9yMzrmC5d5qqkqGOmJTuyZuDxpFchq1Bh/dwYkKLTFHpC+EO9kTvQe4fpnfBaax7QaR1W3id32BHQ1z4UuXKsqYS0pR4Tuc1cwhJA6l+t7JfuRAEcFjFVkh4Lz+UjSIKCibu96f5z1BdjlymFNCS2j1U5znkZKID0SaER1mk6iXC/wqUDwsZqaw46JsC5m0s0FZ/6mhDte97EKRETXXsBfuT7oA==",
  "memo": "test"
}'