본문으로 건너뛰기

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

정보

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

기본 정보​

  1. 협의된 특정 게임은 자체 구현한 결제를 사용할 수 있습니다.
    1. 단, 결제 어뷰징 방지는 게임쪽에서 잘 구현해주셔야합니다.
      1. 예) 저렴한 상품 구매 후 비싼 상품 지급 요청 방지
  2. 게임에서 결제를 구현했지만 매출 인식과 같은 재무 처리 및 플랫폼 기능을 일부 활용하기 위해서 ‘구매 완료 데이터’를 전송해줄 필요가 있습니다.
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/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설명예
pjidString(20)Y

프로젝트ID

  • 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음
1004
playerIdString(50)Y주문 완료를 진행하는 유저ID
ipCountryString(10)N

player의 IP기반 국가코드로 법적 대응을 위해서 수집
testerPurchaseYnString(1)Y

구글 테스터로 등록되어 결제가 진행된 테스트 결제 여부

  • 참고: 결제 검증 과정에서 테스터 결제인지 확인 가능
Y 또는 N
productIdString(200)Y구매를 진행한 상품ID(SKU와 같은 값)google_play_gem_01
microPricelongY

구매 금액 micro단위

  • 사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용
구매 금액 micro단위(예. $0.99는 990,000 µ$. 100만을 곱함)
currencyString(10)Y

구매 금액의 화폐 단위

USD
purchaseOriginalJsonStringY

구매 원본 Json

{"orderId":"GPA.3339-8889-4444-64541","packageName":"com.hybeim.블라블라","productId":"google_com.hybeim.블라블라_gem55000\ .... 블라블라
purchaseSignatureStringY

구매 Signature
memoString(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로 요청
// TODO: Manual review - had fullWidth or overflow attributes

```json
\{
  "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/errorcode))
* 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
  * 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
  * 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.

<table><thead><tr><th width="230">에러코드</th><th>비고</th></tr></thead><tbody><tr><td>SYSTEM_ERROR</td><td><p>빌링 API에서 발생한 시스템 에러</p><ul><li>HTTP 상태코드 500 리턴</li></ul></td></tr><tr><td>NOT_ALLOW_AUTH</td><td>API 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생</td></tr></tbody></table>

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

<table><thead><tr><th width="236">에러코드</th><th>비고</th></tr></thead><tbody><tr><td>INVALID_PARAMETER</td><td> </td></tr><tr><td>NOT_VALID_RECEIPT</td><td><p>구매 영수증 검증</p><ul><li>영수증 변조 등 잘못된 영수증 문제</li></ul></td></tr></tbody></table>

## 요청 curl 샘플

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

```bash
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"
}'