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

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

기본 정보

협의된 특정 게임은 자체 구현한 결제를 사용할 수 있습니다.
1. 단, 결제 어뷰징 방지는 게임쪽에서 잘 구현해주셔야합니다.
  1. 예) 저렴한 상품 구매 후 비싼 상품 지급 요청 방지
게임에서 결제를 구현했지만 매출 인식과 같은 재무 처리 및 플랫폼 기능을 일부 활용하기 위해서 ‘구매 완료 데이터’를 전송해줄 필요가 있습니다.

항목

내용

비고

호출주체

게임서버(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)

프로젝트ID

동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같음

1004

playerId

String(50)

주문 완료를 진행하는 유저ID

ipCountry

String(10)

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

3166-1 alpha-2 국가코드
AWS CloudFront를 사용한다면 HTTP헤더의 CloudFront-Viewer-Country에서 쉽게 얻을 수 있음

testerPurchaseYn

String(1)

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

참고: 결제 검증 과정에서 테스터 결제인지 확인 가능

Y 또는 N

productId

String(200)

구매를 진행한 상품ID(SKU와 같은 값)

google_play_gem_01

microPrice

long

구매 금액 micro단위

사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용

구매 금액 micro단위(예. $0.99는 990,000 µ$. 100만을 곱함)

currency

String(10)

구매 금액의 화폐 단위

3글자 포맷의 ISO-4217

USD

purchaseOriginalJson

String

구매 원본 Json

앱에서 구현시 참고 링크
base64 디코딩된 receiptData

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

purchaseSignature

String

구매 Signature

앱에서 구현시 참고 링크

memo

String(2000)

메모

필요시 옵셔널하게 사용

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

Previous게임쪽에서 결제를 직접 구현한 경우 NextGoogle PC 소모성 상품 구매

Last updated 10 months ago