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

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

기본 정보

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

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

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

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

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

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

항목
내용
비고

호출주체

게임서버(s2s API)

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기반 국가코드로 법적 대응을 위해서 수집

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

구매 금액의 화폐 단위

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

Last updated